Configuration
The evitaDB server is configured in YAML format and its default settings are best described by the following code snippet:
| Abbreviation | Meaning | Example |
|---|---|---|
| K | one thousand | 1K → 1,000 |
| M | one million | 1M → 1,000,000 |
| G | one billion | 1G → 1,000,000,000 |
| T | one trillion | 1T → 1,000,000,000,000 |
| Abbreviation | Meaning | Example |
|---|---|---|
| KB | one kilobyte | 1KB → 1,024 |
| MB | one megabyte | 1MB → 1,048,576 |
| GB | one gigabyte | 1GB → 1,073,741,824 |
| TB | one terabyte | 1TB → 1,099,511,627,776 |
| Abbreviation | Meaning | Example |
|---|---|---|
| 1s | one second | 1s → 1 secs |
| m | one minute | 1m → 60 secs |
| h | one hour | 1h → 3,600 secs |
| d | one day | 1d → 86,400 secs |
| d | one week | 1w → 604,800 secs |
| y | one year | 1y → 31,556,926 secs |
Overriding defaults
Environment Variables
Command Line Arguments
Any configuration property can also be overridden by setting a command line argument with the following format
Application arguments have priority over environment variables.
Custom configuration file
If you have a more complex concatenated pipeline, you can copy multiple files to this folder at different stages of the pipeline - but you must maintain the proper alphabetical order of the files so that overrides are applied the way you want.
Name
Server configuration
This section contains general settings for the evitaDB server. It allows configuring thread pools, queues, timeouts:
- requestThreadPool
Sets limits on the core thread pool used to serve all incoming requests. Threads from this pool handle all queries and updates until the transaction is committed/rolled back. See separate chapter for more information.
- transactionThreadPool
Sets limits on the transaction thread pool used to process transactions when they're committed. I.e. conflict resolution, inclusion in trunk, and replacement of shared indexes used. See separate chapter for more information.
- serviceThreadPool
Sets limits on the service thread pool used for service tasks such as maintenance, backup creation, backup restoration, and so on. See separate chapter for more information.
- queryTimeoutInMilliseconds
Default: 5s
Sets the timeout in milliseconds after which threads executing read-only session requests should timeout and abort their execution.
- transactionTimeoutInMilliseconds
Default: 5m
Sets the timeout in milliseconds after which threads executing read-write session requests should timeout and abort their execution.
- closeSessionsAfterSecondsOfInactivity
Default: 60
It specifies the maximum acceptable period of inactivity before it is forcibly closed by the server side.
- readOnly
Default: false
It switches the evitaDB server into read-only mode, where no updates are allowed and the server only provides read access to the data of the catalogs present in the data directory at the start of the server instance.
- quiet
Default: false
It disables logging of helper info messages (e.g.: startup info). Note that it doesn't disable the main logging handled by the Slf4j logging facade.
This setting should not be used when running multiple server instances inside single JVM because it is currently not thread-safe.
Thread pool configuration
- coreThreadCount
Default: 4
It defines the minimum number of threads in the evitaDB main thread pool, threads are used for query processing, transactional updates and service tasks (vacuuming, cache revalidation). The value should be at least equal to the number of machine cores.
- maxThreadCount
Default: 16
It defines the maximum number of threads in the evitaDB main thread pool. The value should be a multiple of the coreThreadCount value.
- threadPriority
Default: 5
It defines the priority of the threads created in the pool (for future use).
- queueSize
Default: 100
It defines the maximum number of tasks that can accumulate in the queue waiting for the free thread from the thread pool to process them. Tasks that exceed this limit will be discarded (new requests/other tasks will fail with an exception).
Storage configuration
This section contains configuration options for the storage layer of the database.
- storageDirectory
Default: ./data
It defines the folder where evitaDB stores its catalog data. The path can be specified relative to the working directory of the application in absolute form (recommended).
- exportDirectory
Default: ./export
It defines the folder where evitaDB stores its exported files. The path can be specified relative to the working directory of the application in absolute form (recommended). Files are automatically removed according to limits defined in exportFileHistoryExpirationSeconds and exportDirectorySizeLimitBytes.
- lockTimeoutSeconds
Default: 60
It specifies the maximum amount of time the thread may wait to get an exclusive WRITE lock on the file to write its data. Changing this value should not be necessary if everything is going well.
- waitOnCloseSeconds
Default: 60
It specifies a timeout for evitaDB to wait for the release of read handles to a file. If the file handle is not released within the timeout, the calling process will get an exception. Changing this value should not be necessary if everything works fine.
- outputBufferSize
Default: 4MB
The output buffer size determines how large a buffer is kept in memory for output purposes. The size of the buffer limits the maximum size of an individual record in the key/value data store.
- maxOpenedReadHandles
Default: 12
It defines the maximum number of simultaneously opened file read handles.
- computeCRC32C
Default: true
It determines whether CRC32C checksums are calculated for written records in a key/value store, and also whether the CRC32C checksum is checked when a record is read.
It is strongly recommended that this setting be set to true, as it will report potentially corrupt records as early as possible.- minimalActiveRecordShare
Default: 0.5 (when waste exceeds 50% the file is compacted)
Minimal share of active records in the data file. If the share is lower and the file size exceeds also fileSizeCompactionThresholdBytes limit, the file will be compacted. It means new file containing only active records will be written next to original file.
- fileSizeCompactionThresholdBytes
Default: 100MB
Minimal file size threshold for compaction. If the file size is lower, the file will not be compacted even if the share of active records is lower than the minimal share.
- timeTravelEnabled
Default: true
When set to true, the data files are not removed immediately after compacting, but are kept on disk as long as there is history available in the WAL log. This allows a snapshot of the database to be taken at any point in the history covered by the WAL log. From the snapshot, the database can be restored to the exact point in time with all the data available at that time.
- exportDirectorySizeLimitBytes
Default: 1G
It specifies the maximum size of the export directory. If the size of the directory exceeds this limit, the oldest files are removed until the size of the directory is below the limit.
- exportFileHistoryExpirationSeconds
Default: 7d
It specifies the maximum age of the files in the export directory. If the age of the file exceeds this limit, the file is removed from the directory.
Transaction configuration
This section contains configuration options for the storage layer of the database dedicated to transaction handling.
- transactionWorkDirectory
Default: /tmp/evitaDB/transaction
Directory on local disk where Evita creates temporary folders and files for transactional transaction. By default, temporary directory is used - but it is a good idea to set your own directory to avoid problems with disk space.
- transactionMemoryBufferLimitSizeBytes
Default: 16MB
Number of bytes that are allocated on off-heap memory for transaction memory buffer. This buffer is used to store temporary (isolated) transactional data before they are committed to the database. If the buffer is full, the transaction data are immediately written to the disk and the transaction processing gets slower.
- transactionMemoryRegionCount
Default: 256
Number of slices of the transactionMemoryBufferLimitSizeBytes buffer. The more slices the smaller they get and the higher the probability that the buffer will be full and will have to be copied to the disk.
- walFileSizeBytes
Default: 16MB
Size of the Write-Ahead Log (WAL) file in bytes before it is rotated.
- walFileCountKept
Default: 8
Number of WAL files to keep. Increase this number in combination with walFileSizeBytes if you want to keep longer history of changes.
- flushFrequencyInMillis
Default: 1s
The frequency of flushing the transactional data to the disk when they are sequentially processed. If database process the (small) transaction very quickly, it may decide to process next transaction before flushing changes to the disk. If the client waits for WAIT_FOR_INDEX_PROPAGATION he may wait entire flushFrequencyInMillis milliseconds before he gets the response.
Cache configuration
The cache speeds up responses for fully or partially identical queries. The cache might in some case increase the throughput of the system several times.
- enabled
Default: true
This setting enables or disables the use of the cache entirely.
- reflection
Default: CACHE
This setting enables or disables caching of Java reflection information. The CACHE mode is usually recommended unless you're running some kind of test.
- reevaluateEachSeconds
Default: 60
It defines the period for re-evaluating cache adepts to be propagated to cache or pruned. The reevaluation may be also triggered by exceeding maximum allowed anteroomRecordCount, but no later than reevaluateEachSeconds since the last re-evaluation (with the exception when there is no free thread in thread pool to serve this task). See detailed caching process description.
- anteroomRecordCount
Default: 100K
It defines the maximum number of records in cache anteroom. When this count is reached the re-evaluation process is automatically triggered leading to anteroom purge. The anteroom is also periodically purged each reevaluateEachSeconds. See detailed caching process description.
- minimalComplexityThreshold
Default: 10K
It specifies the minimum computational complexity that must be achieved to store the cached result in the cache. It's sort of a virtual number, so there's no guide as to how big it should be. If the cache fills up with a lot of results of doubtful use, you might try to increase this threshold to higher values.
- minimalUsageThreshold
Default: 2
It specifies the minimum number of times a computed result can be reused before it is cached. If the cache is filling up with cached values with low hit ratios, you might try increasing this threshold to higher values.
- cacheSizeInBytes
Default: null, which means that evitaDB uses 25% of the free memory measured at the moment it starts and loads all data into it
evitaDB tries to estimate the memory size of each cached object and avoid exceeding this threshold.
Measuring the exact amount of memory each object allocates is not easy in Java, and at the moment it's only an approximation from our side. According to our experience, our estimates are set higher than the reality and the system stops at around 90% of the set cacheSizeInBytes limit (but this experience is based on OS Linux, x86_64 architecture).
API configuration
This section of the configuration allows you to selectively enable, disable, and tweak specific APIs.
- workerGroupThreads
Default: number of CPUs
Defines the number of IO threads that will be used by Armeria for accept and send HTTP payload.
- idleTimeoutInMillis
Default: 2K
The amount of time a connection can be idle for before it is timed out. An idle connection is a connection that has had no data transfer in the idle timeout period. Note that this is a fairly coarse grained approach, and small values will cause problems for requests with a long processing time.
- requestTimeoutInMillis
Default: 2K
The amount of time a connection can sit idle without processing a request, before it is closed by the server.
- maxEntitySizeInBytes
Default: 2MB
The default maximum size of a request entity. If entity body is larger than this limit then a IOException will be thrown at some point when reading the request (on the first read for fixed length requests, when too much data has been read for chunked requests).
- accessLog
Default: false
It enables / disables access log messages logging for all APIs.
TLS configuration
TLS support is enabled by default for most APIs but can be disabled individually per API in API configs. Note that if you set that each API has different TLS settings, each API must have its own port.
- generateAndUseSelfSigned
Default: true
When set to true, a self-signed certificate authorityToggle Term Reference certificateToggle Term Reference and its private keyToggle Term Reference are automatically generated on server startup and used to communicate with clients.
- folderPath
Default: the sub-folder evita-server-certificates in the working directory
It represents a path to a folder where the generated authority certificate and its private key are stored. This setting is used only when generateAndUseSelfSigned is set to true.
- custom
This section allows you to configure an externally supplied certificateToggle Term Reference. It is only used if the generateAndUseSelfSigned is set to false.
The section requires these nested settings:
- certificate: path to the public part of the certificate file (*.crt)
- privateKey: path to the private key of the certificate (*.key)
- privateKeyPassword: password for the private key
Tip
It is recommended to provide the private key password using command line argument (environment variable) api.certificate.custom.privateKeyPasssword and store id in a CI server secrets vault.Yes there is. You can use standardized way importing the certificate authorityToggle Term Reference certificateToggle Term Reference to the Java trust store. This procedure is described in great detail in this article.
If no custom certificate is configured, the server will not start and an exception will be thrown. The server doesn't provide an unsecured connection for security reasons.
Default endpoint configuration
Default endpoint settings are used as the basis for all endpoints unless overridden in the specific endpoint. This allows you to set common settings for all endpoints in one place.
- enabled
Default: true
It enables / disables a particular web API.
- host
Default: :5555
It specifies the host and port that a particular API should listen on. If the host is not defined, the wildcard address 0.0.0.0 for IPv4 and :: for IPv6 is used instead. If the host is defined as a valid IP address, it's used directly. If the domain name is specified, it's translated into an IP address by the Java DNS lookup and used instead (the resolved IP address may not be the one, you expected - but the result IP is logged to the log and console during the evitaDB server startup, so you can easily check it there).
You may define multiple hosts / ports separated by a comma. The server will listen on all of them.
- exposeOn
Default: localhost
When evitaDB is running in a Docker container and the ports are exposed on the host systems the internally resolved local host name and port usually don't match the host name and port evitaDB is available on that host system.
The exposedHost property allows you to override not only the external hostname, scheme, but also to specify an external port, but the minimum configuration is the hostname. If you don't specify scheme / port, exposed host will assume that the default scheme / port configured for a web API should be used.
- tlsMode
Default: FORCE_TLS
Whether to enable the TLS for a particular API. Three modes are available:
- FORCE_TLS: Only encrypted (TLS) communication is allowed.
- FORCE_NO_TLS: Only unencrypted (non-TLS) communication is allowed.
- RELAXED: Both variants will be available, depending on the client's choice.
- keepAlive
Default: true
If this is set to false server closes connection via HTTP connection: close after each request.
GraphQL API configuration
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_TLS
- parallelize
Default: true
Controls whether queries that fetch data from evitaDB engine will be executed in parallel.
REST API configuration
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_TLS
gRPC API configuration
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_TLS
- exposeDocsService
Default: false
It enables / disables the gRPC service, which provides documentation for the gRPC API and allows to experimentally call any of the services from the web UI and examine its output.
Mutual TLS configuration
- enabled
Default: true
It enables / disables mutual authentication.
- allowedClientCertificatePaths
Default: null
It allows you to define zero or more file paths pointing to public client certificatesToggle Term Reference. Only clients that present the correct certificate will be allowed to communicate with the gRPC web API.
System API configuration
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_NO_TLS
evitaLab configuration
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_TLS
- gui
GUI configuration
This configuration controls how the actual evitaLab web client will be served through HTTP protocol.
- enabled
Default: true
Whether evitaDB should serve the built-in evitaLab web client alongside the evitaLab API.
- readOnly
Default: false
Whether the evitaLab web client should be served in read-only mode. This means that it's runtime data and configuration cannot be changed. It doesn't mean that it will not allow you to change the data of an accessed evitaDB instance. This must be configured at the scope of the evitaDB instance.
- preconfiguredConnections
Default: null
It allows passing a list of evitaDB connections to the web client. These connections will be ready to use by a user of the web client. By default (when null is passed), evitaDB will pass itself as a preconfigured connection for quick access. This can be disabled by passing empty list, or it can be completely overridden by passing a custom list of connections.
It accepts either a path to YAML file prefixed with !include with a list of connections, or a list of connections directly in the configuration. A single connection can be defined as follows:In most cases, evitaDB should be able generate correct configuration by it self. More so, if the api.endpointDefaults.exposeOn property is configured correctly, then it should generate correct configuration even for evitaDB server being behind a proxy. In special cases, this can be overriden by this configuration property, allowing completelly custom connections to multiple different evitaDB server (not just this one).
Observability configuration
The configuration controls all observability facilities exposed to the external systems. Currently, it's the endpoint pro scraping Prometheus metrics, OTEL trace exporter and Java Flight Recorder events recording facilities.
- enabled
Default: true
- host
Default: :5555
- exposedHost
Default: localhost:5555
- tlsMode
Default: FORCE_NO_TLS
- tracing.endpoint
Default: null
Specifies the URL to the OTEL collector that collects the traces. It's a good idea to run the collector on the same host as evitaDB so that it can further filter out traces and avoid unnecessary remote network communication.
- tracing.protocol
Default: grpc
Specifies the protocol used between the application and the OTEL collector to pass the traces. Possible values are grpc and http. gRPC is much more performant and is the preferred option.