12.1 Every setting in relatude.db.json

The file is one JSON object, read into RelatudeDBServerSettings. Keys are case-insensitive, enums are written as names ("LocalDisk", "Native"), and // comments are allowed, though trailing commas are not. The tables list every key by the object it sits on. The default is the value used when the key is left out.

The admin login. These keys protect the admin UI. They have nothing to do with your application's own users.

A request counts as local only when it comes from a loopback address with no sign of a proxy: no forwarding headers, and not hosted behind IIS, Azure App Service or Kubernetes. Behind a reverse proxy nobody is local, so you need MasterUserName, MasterPassword and AllowMasterLoginOutsideLocalhost, or Sign in with Relatude Services (below).

Relatude Services. The account an installation uses for hosted AI, imaging, files to text and text messages, and for signing in to the admin UI (§35). All of it is optional: without ApiKey, nothing is charged and nothing is reported.

ShortName. A database's shared settings files are its log definitions, its GraphQL endpoints (§33.2) and its datamodel overrides. With a short name they live in relatude.settings/<ShortName>/; without one, directly in relatude.settings/. That is all you need with one database. Short names must be unique, and only one database can go without one. Set it in relatude.db.json, so that every installation reads the same folder.

A LocalDisk path must stay inside the root data folder, even an absolute one, or the server refuses it. To keep the data somewhere else, move the root data folder with ServerOptions.DefaultDataFolderPath, which moves relatude.settings/ along with it. Several roles can share one backend: inside it, the log, state, backups, logs and indexes each get their own folder.

Blob leases. A lease lasts 60 seconds and is renewed while the stream is open. A process that dies without letting go keeps its blobs locked for at most a minute: an open that finds a blob leased waits up to 75 seconds, then fails with a FileLockedException. A lease that never ends, one taken by another tool for example, blocks every open of its blob. To release it, open Files in the admin UI on that storage and press Leases. It lists the leased blobs and breaks the leases this server does not hold itself. Break them only when no other instance uses the storage.

FileStoreSettings — where file bytes live

A new database gets one MultiFile store that keeps one copy per content and hashes with SHA256, as in the example above, and LocalSettings.DefaultFileStore names it. FileStoreSettings.CreateMultiFile(ioProviderId) makes the same store in code.

A store written in JSON without SameHashSameFile and HashAlgorithm gets false and MD5. A store made in code, by the CLI or by the admin UI gets true and SHA256, and writes both keys out. So when you add a store by hand, write both keys. A SingleFile store ignores them.

When DefaultFileStore is not set, uploads go to an implicit store: MultiFile on IoDatabase, one file per upload, MD5. Each file records the store it went into, and the implicit store's id is the empty Guid. If you name a configured store as DefaultFileStore later, new uploads go there and the earlier files are still read from the implicit store.

Moving files to another store

Changing DefaultFileStore, SameHashSameFile or HashAlgorithm affects new uploads only. To bring the stored files along, use Storage › File storage › Rewrite files… in the admin UI. Choose the store to write into and how it writes: the hash, and Same hash, same file. Those two are saved as the store's own settings and apply to new uploads at once. They cannot be chosen for the implicit store, for a SingleFile store, or where configuration or code sets them. The job runs in the background while the database stays in use.

• It writes every file that belongs in the store, wherever the file is now: the files of the properties that upload into it, as the default store or by name. Revisions and embedded objects are included. Files of properties that upload elsewhere stay where they are, so a store nothing uploads into has nothing to rewrite: make it the default first.
• The target store writes each copy with its own hash, layout and sharing. A file that several values share is copied once. Name, image size, meta data and extracted text are kept, and nothing is indexed again.
• A file already in the store is rewritten only where the store would now write it differently: with another hash, or not yet kept by its hash. So after you change a store's hash or turn on Same hash, same file, a rewrite into the same store brings its existing files in line.
• A value that changes during the copy, a new upload for example, is left alone. A file that cannot be read is reported and its value is left as it was. Running the job again picks up whatever is left, including the rest of a cancelled run.
• The old copies stay where they are, because older versions in a node's history still point at them. Storage › Missing and redundant files removes them; after that, those older versions have no file.

From code:

RewriteFilesAsync(fromStoreId, toStoreId, …) moves every file of one store into another, whatever store its property uploads to. Guid.Empty names the implicit store. Both return a RewriteFilesResult with the counts and the values that could not be rewritten. SetFileStoreWriteOptions(storeId, sameHashSameFile, hashAlgorithm) changes how an open MultiFile store writes new files; at the next open, the settings decide again.

AISettings — embeddings, completions and the vector index

AISettings gives a database an AI provider for embeddings, which semantic search uses, and for completions. TypeName picks the provider. All of these are built into Relatude.DB.Server, so there is nothing extra to install:

With RelatudeServices on a server, leave ApiKey empty: calls are paid with the installation's own API key. Its models are names the service publishes, and left empty the service picks its default. The license needs a credit account with a balance for each kind of call: ai_embeddings for embeddings and ai_completion for completions.

The vector index engine is not an AI setting. Choose it in LocalSettings with VectorIndexes and DefaultVectorIndex, below. Semantic indexes exist only on a database with AISettings.

LocalSettings — the engine

Every key has a working default. The groups start with the ones you change most often.

Indexing. What is indexed, and by which engine. Without engines, every index is kept in memory and loaded again at each open, which suits small databases only. A new relatude.db.json has a Native value engine and a Native text engine, with the defaults pointing at them. This example also keeps the vectors on disk:

Culture, access and files.

Durability. How soon writes reach the disk. The defaults can lose the last second of writes in a crash, but never corrupt the database.

State snapshots. A snapshot lets the next open skip replaying the log from the start.

Backups. Off by default. The admin UI takes a backup with one click either way.

With AutoBackUp on, a backup is taken every hour. The finest generation above 0 sets the pace: with NoHourlyBackUps at 0 a backup is taken once a day, with NoDailyBackUps at 0 too, once a week, and so on. With all five at 0 there are no automatic backups, and the existing ones are deleted unless they are marked keep.

Log truncation. The transaction log grows until something rewrites it.

Caches. Sizes in gigabytes. Both are upper limits, not reservations.

Background tasks and diagnostics.