Settings

dumpConfigAtStartup

Dumps the configuration at startup

Boolean

false

dumpMetricsEvery

Dumps the metrics at startup, shutdown and every configurable amount of time (in seconds)

Long

0

opencypher.idBucketBits

Number of bits reserved for the bucketId when packing a RID into the numeric value returned by the Cypher id() function (and SQL’s .asCypherRID() method). Out of the 63 usable bits (the sign bit is kept clear so id(n) is never negative), this many go to the bucketId and the rest to the record position. The default of 16 allows up to 65536 buckets and ~1.4e14 positions per bucket. Increase it for databases with many buckets, decrease it for buckets holding a very high number of records. Must be between 1 and 31. Changing it alters the id() output, so encode and decode must use the same value

Integer

16

profile

Specify the preferred profile among: default, high-performance, low-ram, low-cpu

String

default

test

Tells if it is running in test mode. This enables the calling of callbacks for testing purpose

Boolean

false

backup.enabled

State of backup lock. Disable for increased performance of massive insertions.

Boolean

True

ha.appendBufferSize

AppendEntries batch byte limit for replication (e.g. '4MB'). Since v26.4.1

String

4MB

ha.appendElementLimit

Maximum number of Raft log entries per AppendEntries batch. Bounds the per-batch in-memory footprint on the follower during catch-up resync, where many batches may queue before the state machine can apply them. Lowering this value reduces peak heap pressure on followers catching up from a far-behind state. The byte limit (ha.appendBufferSize) remains the dominant per-batch heap bound; this element count is the secondary cap that governs when entries are small enough that many fit under the byte limit. Must be a positive integer (>= 1). Since v26.7.1

Integer

64

ha.clientElectionRetryCount

Number of retries performed by RemoteDatabase after receiving HTTP 503 NeedRetryException during an election. Since v26.4.1

Integer

3

ha.clientElectionRetryDelayMs

Delay in ms between RemoteDatabase election retries. Since v26.4.1

Long

2000

ha.bootstrapFromLocalDatabase

When true (default), at first cluster formation peers exchange (fingerprint, lastTxId) per database; the highest-lastTxId peer is elected as bootstrap source via leadership transfer. Matching peers bootstrap locally with zero bytes transferred; mismatched peers reinstall the leader-shipped full snapshot. Since v26.5.1

Boolean

true

ha.bootstrapTimeoutMs

Maximum time in ms the bootstrap leader waits for every configured peer to report its bootstrap state before proceeding. Since v26.5.1

Long

120000

ha.clusterName

Cluster name. Useful in case of multiple clusters in the same network

String

arcadedb

ha.clusterToken

Shared secret for inter-node authentication. If empty, auto-generated at first startup and persisted under raft-storage/. Since v26.4.1

String

ha.clusterTokenPath

Path to a file containing the shared secret for inter-node authentication. Read only when ha.clusterToken is not set; the file content is trimmed of surrounding whitespace. Keeps the secret off the command line (e.g. a Kubernetes Secret mounted on tmpfs). Since v26.6.1

String

null

ha.electionTimeoutMin

Minimum Raft election timeout in ms. Increase for high-latency WAN clusters. Since v26.4.1

Integer

2000

ha.electionTimeoutMax

Maximum Raft election timeout in ms. Increase for high-latency WAN clusters. Since v26.4.1

Integer

5000

ha.enabled

True if HA is enabled for the current server

Boolean

false

ha.errorRetries

Number of automatic retries in case of IO errors with a specific server. 0 (default) is to retry against all the configured servers

Integer

0

ha.grpcAllowlistRefreshMs

Rate-limiting interval in ms for DNS re-resolution in the gRPC peer address allowlist filter. Since v26.4.1

Long

30000

ha.grpcFlowControlWindow

gRPC flow control window size in bytes for Raft AppendEntries traffic. Larger values help catch-up replication after partitions. Since v26.4.1

Long

4194304

ha.groupCommitBatchSize

Maximum number of Raft log entries to batch in a single group commit flush. Higher values improve throughput under concurrent load. Since v26.4.1

Integer

500

ha.groupCommitOfferTimeout

Timeout in ms waiting for space in the group-commit queue before throwing ReplicationQueueFullException. Since v26.4.1

Integer

100

ha.groupCommitQueueSize

Maximum pending transactions allowed in the Raft group-commit queue. When full, the server sheds load by throwing ReplicationQueueFullException (NeedRetryException). Since v26.4.1

Integer

10000

ha.healthCheckInterval

Interval in ms for the Raft health monitor to check for CLOSED/EXCEPTION state and auto-recover. 0 disables. Since v26.4.1

Long

3000

ha.idempotencyCacheMaxEntries

Maximum number of entries in the HTTP idempotency cache. Since v26.4.1

Integer

10000

ha.idempotencyCacheTtlMs

Time-to-live in ms for entries in the HTTP idempotency cache. Since v26.4.1

Long

60000

ha.k8s

The server is running inside Kubernetes (enables auto-join on scale-up)

Boolean

false

ha.k8sSuffix

When running inside Kubernetes use this suffix to reach the other servers. Example: arcadedb.default.svc.cluster.local

String

ha.logPurgeGap

Number of Raft log entries retained after a snapshot as a buffer for slightly lagging followers. Lower values free disk faster but raise the chance a slow follower needs a full snapshot resync. Since v26.4.1

Integer

1024

ha.logPurgeUptoSnapshot

When true, deletes old Raft log segments after each snapshot to bound disk growth. Set to false to retain full log history for debugging/auditing. Since v26.4.1

Boolean

true

ha.logSegmentSize

Maximum Raft log segment size (e.g. '64MB', '128MB'). Since v26.4.1

String

64MB

ha.logVerbose

Verbose HA logging: 0=off, 1=basic (elections), 2=detailed (replication), 3=trace (every state machine apply). Since v26.4.1

Integer

0

ha.peerAllowlist.enabled

Reject inbound Raft gRPC connections whose remote address does not resolve to a host in ha.serverList. Loopback is always allowed. Not a substitute for mTLS on untrusted networks. Since v26.4.1

Boolean

true

ha.peerAllowlistStartupGraceMs

Startup grace window in ms during which the gRPC peer allowlist fails OPEN (accepts and logs a warning) for an unmatched address, as long as it has never resolved every host in ha.serverList at least once. Prevents a self-inflicted partition on Kubernetes, where a peer’s headless-service DNS record is only published once its pod is Ready, so a restarting peer connects before its own name resolves. Measured from filter creation; enforces normally once all peers resolve once or the window elapses. 0 disables fail-open. Since v26.6.1

Long

60000

ha.peerAllowlistStickyTtlMs

How long in ms the gRPC peer allowlist keeps the last successfully-resolved IPs of a peer host when a later DNS re-resolution of that host fails. Bridges transient DNS outages and pod-IP churn so a peer that resolved moments ago is not evicted by a momentary lookup failure. 0 disables stickiness. Since v26.6.1

Long

300000

ha.peerChannelResetDuration

Time in ms a follower must stay continuously unreachable before the leader resets that one follower’s replication gRPC channel, so the next send re-resolves DNS and reconnects. Recovers a leader appender stuck on a stale DNS result after a follower restarts with a new address (e.g. a Kubernetes pod-IP change). Retried once per interval, up to 5 attempts, then the leader gives up or escalates (see ha.peerChannelResetEscalation); the counter re-arms when the follower reconnects. Only the unreachable peer’s channel is touched. Requires ha.peerUnreachableThreshold > 0. Set to 0 to disable. See Replication-Channel Self-Healing. Since v26.7.2

Long

60000

ha.peerChannelResetEscalation

When the ha.peerChannelResetDuration retry budget is exhausted and the follower’s replication channel is still dead, transfer leadership to a healthy peer so the new leader builds a fresh appender to that follower. Without it the leader stays wedged until an operator restarts the process, because the reset streak only re-arms when the follower becomes reachable again. The target is chosen with the same rules as a manual step-down and is never the wedged follower; when no healthy target exists the leader logs for operator intervention instead. Each healthy peer escalates a given follower at most once per 30-minute cooldown, so leadership churn is bounded rather than perpetual. Set to false to only log. See Replication-Channel Self-Healing. Since v26.8.1

Boolean

true

ha.peerUnreachableThreshold

Time in ms since the last successful RPC to a follower before the leader reports it as unreachable in the resync narrative. Also the "unreachable" signal ha.peerChannelResetDuration depends on. Does not change Raft membership or quorum. Set to 0 to disable, which also disables the channel-reset recovery built on it. Since v26.7.2

Long

10000

ha.proxyConnectTimeout

Connect timeout in ms for the leader proxy (replica-to-leader forwarding). Since v26.4.1

Long

5000

ha.proxyMaxBodySize

Maximum request body size in bytes the leader proxy will buffer and forward. Since v26.4.1

Integer

16777216

ha.proxyReadTimeout

Read timeout in ms for the leader proxy. Covers long-running queries forwarded from a replica. Since v26.4.1

Long

30000

ha.quorum

Write quorum: majority or all. Legacy values none, one, two, three removed in v26.4.1

String

majority

ha.quorumTimeout

Timeout in ms waiting for the quorum acknowledgment

Long

10000

ha.raftPort

TCP/IP port for Raft gRPC communication. Used as the default when HA_SERVER_LIST entries do not specify an explicit port. Since v26.4.1

Integer

2434

ha.raftPersistStorage

If true, the Raft storage directory is preserved across restarts, enabling node rejoin by replaying its persisted log instead of a full snapshot resync. Defaults to true since v26.7.2 (previously false): wiping the Raft log on restart could permanently diverge a lagging follower after a full-cluster cold restart (WALVersionGapException) or silently re-form a fresh single-node cluster. Ensure ha.raftStorageDirectory lives on durable storage. A throwaway/test cluster can opt out with false. Since v26.4.1

Boolean

true

ha.raftStorageDirectory

Parent directory under which the per-node Raft storage sub-folders (raft-storage-<nodeName>) are created. When empty (the default), the server root path (arcadedb.server.rootPath) is used. Because ha.raftPersistStorage now defaults to true, this directory must live on durable storage (a persistent volume, not an ephemeral/tmpfs mount) so a restarted node can replay its log and rejoin without a full snapshot resync. Set this to a writable, statically-named path (e.g. a PVC mount) on Kubernetes StatefulSets with readOnlyRootFilesystem: true, where the dynamically-named raft-storage-* directory under the read-only server root cannot be created or mounted. (Available since v26.6.1)

String

ha.ratisRestartMaxRetries

Maximum consecutive Ratis restart attempts by the health monitor before the server shuts down for cluster-level recovery. Since v26.4.1

Integer

10

ha.readConsistency

Default read consistency for replica reads: eventual, read_your_writes, linearizable. Since v26.4.1

String

read_your_writes

ha.replicationChunkMaxSize

Maximum channel chunk size for replicating messages between servers

Integer

16777216

ha.replicationLagWarning

Raft log index gap threshold for replication lag warnings. 0 to disable. Since v26.4.1

Long

1000

ha.serverList

Servers in the cluster, comma-separated. Each entry uses the readable object form [name@]host:{raft:2434,http:2480,https:2490,priority:10} (recommended) or the positional form [name@]host:raftPort:httpPort[:priority[:httpsPort]]. The httpPort is required for replica-to-leader HTTP forwarding. The optional name@ prefix (since v26.5.1) gives the peer a human-readable name used in logs and Studio. The optional priority (default 0) prefers higher-valued nodes during elections. The optional httpsPort (since v26.6.1) encrypts peer-to-peer transfers (e.g. snapshot download) when ssl.enabled is true; on a homogeneous cluster it is derived from this node’s local HTTPS port when omitted. Example: frankfurt@db1:{raft:2434,http:2480,https:2490,priority:10},london@db2:{raft:2434,http:2480,https:2490}

String

ha.serverRole

Node role in the cluster: any (default, eligible for leader election) or replica (never elected leader; Raft priority set to 0). Useful for witness/read-scale nodes. Since v26.4.1

String

any

ha.snapshotDownloadTimeout

Read timeout in ms for downloading a database snapshot from the leader during follower resync. Since v26.4.1

Integer

300000

ha.snapshotGapTolerance

Maximum acceptable gap between the snapshot index and persisted applied index before triggering a snapshot download. Since v26.4.1

Long

10

ha.snapshotInstallRetries

Maximum retry attempts for snapshot download from the leader during snapshot installation. Since v26.4.1

Integer

3

ha.snapshotInstallRetryBaseMs

Base delay in ms for exponential backoff between snapshot download retries. Actual delay is baseMs * 2^attempt. Since v26.4.1

Long

5000

ha.snapshotMaxConcurrent

Maximum number of concurrent snapshot downloads served by the leader. Requests over this limit receive HTTP 503. Since v26.4.1

Integer

2

ha.snapshotMaxEntrySize

Maximum uncompressed size in bytes for a single entry in a snapshot ZIP. Decompression-bomb guard. Since v26.4.1

Long

10737418240

ha.snapshotThreshold

Number of Raft log entries after which the leader automatically takes a snapshot. Since v26.4.1

Long

100000

ha.snapshotWatchdogTimeout

Delay in ms before the snapshot-gap watchdog triggers a download. Floored at 4x ha.electionTimeoutMax. Since v26.4.1

Long

30000

ha.snapshotWriteTimeout

Timeout in ms for writing a snapshot to a follower. If the transfer stalls beyond this duration, the connection is force-closed. Since v26.4.1

Long

300000

ha.stalledReplicaResyncDurationMs

How long in ms a replica must stay continuously STALLED — its matchIndex not advancing while the leader keeps committing — before the leader forces it to resync. This is the leader-driven counterpart to a follower detecting its own lag: it covers the case where the follower cannot self-detect the stall because its own commit index never advances. A follower still at the never-appended sentinel (matchIndex=-1 while the leader holds committed entries) is treated as STALLED regardless of the numeric lag, so it is recovered even when the leader is only a few entries ahead and the lag stays below ha.replicationLagWarning. The same duration doubles as the grace period before a replica’s status flips from HEALTHY to STALLED, so a brief join or snapshot-install window is not misreported. Set to 0 to disable leader-driven recovery; the STALLED condition is still detected and logged. Since v26.7.2

Long

60000

ha.stopServerOnReplicationFailure

After a phase-2 replication failure, step-down is attempted first. If every step-down fails and this flag is true, the JVM exits so an orchestrator can restart. Default is false: the server keeps running and logs CRITICAL. Since v26.4.1

Boolean

false

ha.writeBufferSize

Raft log write buffer size (e.g. '8MB'). Must be at least ha.appendBufferSize + 8 bytes; otherwise the server fails to start with ConfigurationException. Since v26.4.1

String

8MB

network.sameServerErrorRetry

Number of automatic retries in case of IO errors with a specific server. If replica servers are configured, look also at HA_ERROR_RETRY setting. 0 (default) = no retry

Integer

0

network.socketTimeout

TCP/IP Socket timeout (in ms)

Integer

30000

network.maxPreAuthConnections

Maximum number of connections a binary wire-protocol listener (Postgres, Redis, BOLT) may hold in the phase before authentication. Each accepted socket costs one thread and one file descriptor before the client has proved who it is, and network.socketTimeout only bounds how long each one may stay there, not how many there can be. Past this cap the listener closes further connections immediately rather than accepting and then timing them out. The cap is per listener, so a flood against one protocol cannot use up the budget that lets clients of another log in. 0 means unlimited. Since v26.9.1

Integer

500

network.socketKeepAlive

Enable TCP keepalive (SO_KEEPALIVE) on every wire-protocol socket. The Postgres and Redis executors drop the socket read timeout to infinite once a connection is authenticated, because an authenticated client legitimately holds an idle connection open, and those protocols carry no application-level heartbeat. With keepalive off, a peer that dies without a FIN/RST (host crash, silent partition) leaves the server thread blocked in a read forever, leaking a thread and a file descriptor per event. Keepalive lets the OS discover the dead peer and fail the read. Since v26.9.1

Boolean

true

network.socketKeepAliveIdle

Seconds an authenticated connection may sit idle before the OS sends the first TCP keepalive probe. Only applied where the JDK and the platform expose TCP_KEEPIDLE (Linux and macOS do); elsewhere the system-wide default applies, typically 2 hours. 0 leaves the system default in place. Since v26.9.1

Integer

120

network.socketKeepAliveInterval

Seconds between TCP keepalive probes once the first one has gone unanswered. 0 leaves the system default in place. Since v26.9.1

Integer

15

network.socketKeepAliveCount

Number of unanswered TCP keepalive probes after which the connection is declared dead. With the defaults a dead peer is detected about 3 minutes after the connection goes idle. 0 leaves the system default in place. Since v26.9.1

Integer

4

ssl.keyStore

Path where the SSL certificates are stored

String

null

ssl.keyStorePass

Password to open the SSL key store

String

null

ssl.trustStore

Path to the SSL trust store

String

null

ssl.trustStorePass

Password to open the SSL trust store

String

null

ssl.enabled

Use SSL for client connections

Boolean

false

postgres.debug

Enables the printing of Postgres protocol to the console. Default is false

Boolean

false

postgres.host

TCP/IP host name used for incoming connections for Postgres plugin. Default is '0.0.0.0'

String

0.0.0.0

postgres.port

TCP/IP port number used for incoming connections for Postgres plugin. Default is 5432

Integer

5432

redis.defaultDatabase

Default database name for Redis protocol connections. If set, RAM commands (SET, GET, etc.) will use this database’s globalVariables. Empty means no default (requires SELECT command or key prefix)

String

redis.host

TCP/IP host name used for incoming connections for Redis plugin. Default is '0.0.0.0'

String

0.0.0.0

redis.port

TCP/IP port number used for incoming connections for Redis plugin. Default is 6379

Integer

6379

mongo.host

TCP/IP host name used for incoming connections for Mongo plugin. Default is '0.0.0.0'

String

0.0.0.0

mongo.port

TCP/IP port number used for incoming connections for Mongo plugin. Default is 27017

Integer

27017

server.databaseLoadAtStartup

Open all the available databases at server startup

Boolean

true

server.databaseDirectory

Directory containing the database

String

${arcadedb.server.rootPath}/databases

server.backupDirectory

Directory containing the backups

String

${arcadedb.server.rootPath}/backups

server.logsDirectory

Directory where the server writes its log files. Useful on read-only root filesystems (e.g. Kubernetes readOnlyRootFilesystem pods) to relocate logs to a writable mount. The value is resolved very early at startup from, in order, the system property arcadedb.server.logsDirectory, the environment variable, then this setting, and supports ${…​} placeholders. The server.sh/server.bat scripts forward the ARCADEDB_LOG_DIR environment variable to this setting. (Available since v26.6.1)

String

./log

server.defaultDatabases

The default databases created when the server starts. The format is (<database-name>[(<user-name>:<user-passwd>[:<user-group>])])[{import|restore:<URL>}][;]'. Pay attention on using `; to separate databases and , to separate credentials. The supported actions are import and restore. Example: Universe[albert:einstein:admin];Amiga[Jay:Miner,Jack:Tramiel]{import:/tmp/movies.tgz}

String

server.defaultDatabaseMode

The default mode to load pre-existing databases. The value must match a com.arcadedb.engine.PaginatedFile.MODE enum value: {READ_ONLY, READ_WRITE}Databases which are newly created will always be opened READ_WRITE.

String

READ_WRITE

server.httpIncomingHost

TCP/IP host name used for incoming HTTP connections

String

0.0.0.0

server.httpIncomingPort

TCP/IP port number used for incoming HTTP connections. Specify a single port or a range <from>-<to>. Default is 2480-2489 to accept a range of ports in case they are occupied.

String

2480-2489

server.httpsIncomingPort

TCP/IP port number used for incoming HTTPS connections. Specify a single port or a range <from>-<to>. Default is 2490-2499 to accept a range of ports in case they are occupied.

String

2490-2499

server.httpsIoThreads

Number of threads to use in the HTTP server

Integer

2 per core

server.httpTxExpireTimeout

Timeout in seconds for a HTTP transaction to expire. This timeout is computed from the latest command against the transaction

Long

30

server.httpBodyContentMaxSize

Maximum size in bytes for HTTP request body content. Set to -1 for unlimited size. Default is 100MB

Integer

100

server.httpAuthSessionExpireTimeout

Timeout in seconds for a HTTP authentication session to expire. This timeout is computed from the latest request using the auth token. See Token-Based Authentication. (Available since v26.2.1)

Long

1800

server.httpAuthSessionMax

Maximum number of concurrent HTTP authentication sessions the server keeps in memory. Once reached, a further POST /api/v1/login is answered 503 instead of growing the session map without bound; expired sessions are reclaimed before refusing. Set to 0 for unlimited (not recommended). (Available since v26.9.1)

Integer

10000

server.httpAuthSessionMaxPerUser

Maximum number of concurrent HTTP authentication sessions a single user may hold. Beyond it, that user’s oldest session is invalidated to make room for the new one, so a login loop recycles only its own sessions and never affects other users. Set to 0 for unlimited (not recommended). (Available since v26.9.1)

Integer

100

server.mode

Server mode between 'development', 'test' and 'production'

String

development

server.name

Server name

String

ArcadeDB_0

server.plugins

Server plugins to load, see available plugins. Format as comma separated list of: <pluginName>:<pluginFullClass>.

String

server.rootPassword

Password for root user to use at first startup of the server. Set this to avoid asking the password to the user

String

null

server.rootPasswordPath

Path to file with password for root user to use at first startup of the server. Set this to avoid asking the password to the user

String

null

server.rootPath

Root path in the file system where the server is looking for files. By default is the current directory

String

null

server.securityAlgorithm

Default encryption algorithm used for passwords hashing

String

PBKDF2WithHmacSHA256

server.reloadEvery

Time in milliseconds of checking if the server security files have been modified to be reloaded

Integer

5000

server.securitySaltCacheSize

Cache size of hashed salt passwords. The cache works as LRU. Use 0 to disable the cache

Integer

64

server.saltIterations

Number of iterations to generate the salt or user password. Changing this setting does not affect stored passwords

Integer

65536

server.eventBusQueueSize

Size of the queue used as a buffer for unserviced database change events.

Integer

1000

server.eventBusMaxPendingBytes

Maximum number of bytes of change-stream frames that may be outstanding towards a single WebSocket subscriber before it is evicted. Frames are sent asynchronously, so a subscriber that never reads accumulates them in the server’s send buffer: the producer-side queue is bounded but a slow consumer is charged to the server’s heap, not to its own. Past this cap the subscription is dropped and the channel closed, which is what the client would experience anyway. 0 disables the cap. Since v26.9.1

Long

16777216

server.readinessRequiresHA

When true and HA is active, /api/v1/ready also requires the node to have joined the Raft group (a leader has been elected). Default false preserves current readiness behavior. See Health probes. (Available since v26.7.1)

Boolean

false

server.readinessHAMaxLag

When server.readinessRequiresHA is true, the maximum number of Raft log entries a follower may lag behind the commit index (commitIndex - lastAppliedIndex) and still report Ready. Keeps /api/v1/ready returning 503 until a (re)joined follower has replayed the committed log, so a rolling restart does not drop the write quorum. See Health probes. (Available since v26.7.1)

Long

100

server.logFormat

Console log format: text (default, human-readable) or json (one JSON object per line with correlation fields). See Structured logging. (Available since v26.7.1)

String

text

server.logIncludeTrace

In text log mode, append [traceId=…​] to each line while a trace is active. Default false preserves current text output. (Available since v26.7.1)

Boolean

false

server.grpcQueryMaxResultRows

Hard ceiling on the number of rows the gRPC unary ExecuteQuery materializes. A request limit at or below this cap is honored; a result that would exceed it fails the call with RESOURCE_EXHAUSTED (consistent with the StreamQuery MATERIALIZE_ALL path) rather than silently truncating, and a client cannot bypass it with a larger limit. Bounds heap usage and protects against limitless-query denial-of-service. The default is lower than server.grpcStreamMaxMaterializedRows because the unary response is built and returned as a single gRPC message (also bounded by the max message size), whereas StreamQuery emits incrementally. Set to -1 or 0 for unlimited (removes the DoS protection). (Available since v26.7.1)

Integer

100000

server.grpcStreamMaxMaterializedRows

Maximum number of rows the gRPC StreamQuery MATERIALIZE_ALL retrieval mode buffers in memory before emitting. Exceeding the cap fails the call with RESOURCE_EXHAUSTED so clients fall back to CURSOR/PAGED streaming instead of running the server out of memory. Set to -1 or 0 for unlimited (removes the DoS protection). (Available since v26.7.1)

Integer

1000000

server.grpcStreamWriteTimeoutMs

Maximum time in milliseconds a gRPC StreamQuery worker waits for the client transport to become ready to accept the next batch before aborting the stream. Prevents a slow or abandoned client from pinning the worker thread (and the open ResultSet/transaction) indefinitely. Set to -1 to wait forever (removes the DoS protection). (Available since v26.7.1)

Long

60000

serverMetrics

True to enable metrics

Boolean

true

serverMetrics.logging

True to enable metrics logging

Boolean

true

serverMetrics.prometheus.requireAuthentication

Require authentication on the /prometheus scrape endpoint exposed by the Prometheus metrics plugin (plugin-level key, read by the optional metrics module).

Boolean

true

serverMetrics.otlp.enabled

Register an OTLP metrics registry alongside the /prometheus scrape, pushing metrics to serverMetrics.otlp.endpoint. Requires serverMetrics=true. Plugin-level key read by the optional metrics module. See Metrics depth. (Available since v26.7.1)

Boolean

false

serverMetrics.otlp.endpoint

OTLP metrics export endpoint (gRPC), used when serverMetrics.otlp.enabled=true. (Available since v26.7.1)

String

http://localhost:4317

serverMetrics.tracing.enabled

Enable OpenTelemetry distributed tracing (requires the optional tracing plugin on the classpath, shipped in the full distribution). Query/command spans include the statement text as the db.statement span attribute, which may contain sensitive data, so secure the OTLP collector endpoint. See Distributed tracing. (Available since v26.7.1)

Boolean

false

serverMetrics.tracing.endpoint

OTLP trace export endpoint (gRPC). (Available since v26.7.1)

String

http://localhost:4317

serverMetrics.tracing.samplingRate

Parent-based trace sampling ratio in [0.0,1.0]. 1.0 samples everything, 0.0 disables sampling. (Available since v26.7.1)

Float

0.0

studio.enabled

Force-enable the Studio web tool even when the server runs in production mode. In development and test mode Studio is always served; in production mode it is disabled by default and this setting can re-enable it. See how-to/operations/server.adoc#production-mode-defaults

Boolean

false

asyncOperationsQueueImpl

Queue implementation to use between 'standard' and 'fast'. 'standard' consumes less CPU than the 'fast' implementation, but it could be slower with high loads

String

standard

asyncOperationsQueueSize

Size of the total asynchronous operation queues (it is divided by the number of parallel threads in the pool)

Integer

1024

asyncBackPressure

When the asynchronous queue is full at a certain percentage, back pressure is applied

Integer

0

asyncTxBatchSize

Maximum number of operations to commit in batch by async thread

Integer

10240

asyncWorkerThreads

Number of asynchronous worker threads. By default it is cores minus 1, but at least 1

Integer

(machine dependent)

bucketDefaultPageSize

Default page size in bytes for buckets. Default is 65536

Integer

65536

bucketReuseSpaceMode

Mode used to reuse space in pages. Use 'low' to have faster updates consuming more space on disk, medium for balance. Default is 'high'

String

high

bucketWipeOutOnDelete

Wipe out record content on delete. If enabled, assures deleted records cannot be analyzed by parsing the raw files and backups will be more compressed, but it also makes deletes a little bit slower

Boolean

true

command.timeout

Default timeout for commands (in ms)

Long

0

command.warningsEvery

Reduce warnings in commands to print in console only every X occurrences. Use 0 to disable warnings with commands

Integer

100

commitLockTimeout

Timeout in ms to lock resources during commit

Long

5000

cypher.algoMaxWorkingMemory

Maximum heap, in bytes, that a single algo.* procedure call may reserve for its dense working set: walk buffers, embedding matrices, nodeCount x nodeCount distance/similarity/neighbor matrices, terminal-pair tables, and (as of v26.9.1) the loaded graph itself (vertex list, RID index, adjacency list). A call over budget is refused before allocating, naming the offending component. Negative means no limit. Default auto-scales with the JVM max heap (1/8 of it, never below 64MB). Graph load coverage added in v26.9.1

Long

64MB (auto-scaled)

cypher.statementCache

Max number of entries in the cypher statement cache. Use 0 to disable. Caching statements speeds up execution of the same cypher queries

Integer

1000

opencypher.loadCsv.allowFileUrls

Allow LOAD CSV to access local files via file:/// URLs and bare file paths. Disable for security in multi-tenant server deployments. In production server mode, this is automatically set to false if not explicitly configured. See how-to/operations/server.adoc#production-mode-defaults

Boolean

true

opencypher.loadCsv.importDirectory

Root directory for LOAD CSV file:/// URLs. When set, file paths are resolved relative to this directory and path traversal (../) is blocked. Empty string means no restriction

String

(empty)

dateFormat

Default date format using Java SimpleDateFormat syntax

String

yyyy-MM-dd

dateImplementation

Default date implementation to use on deserialization. By default java.util.Date is used, but the following are supported: java.util.Calendar, java.time.LocalDate

Class

class java.util.Date

dateTimeFormat

Default date time format using Java SimpleDateFormat syntax

String

yyyy-MM-dd HH:mm:ss

dateTimeImplementation

Default datetime implementation to use on deserialization. By default java.util.Date is used, but the following are supported: java.util.Calendar, java.time.LocalDateTime, java.time.ZonedDateTime

Class

class java.util.Date

deleteTolerateBrokenChain

When true, a DELETE of a record whose multi-page chunk chain is structurally corrupted removes the record anyway, skipping the index cleanup it cannot read and leaving any unreachable chunks for CHECK DATABASE FIX to reclaim. When false (the default) such a delete is refused with a BrokenChunkChainException naming the record, so corruption is never removed silently. Genuine transaction conflicts are unaffected by this setting: they keep retrying either way. CHECK DATABASE FIX removes a corrupted record regardless of this setting

Boolean

false

flushOnlyAtClose

Never flushes pages on disk until the database closing

Boolean

false

freePageRAM

Percentage (0-100) of memory to free when Page RAM is full

Integer

50

gavPersistCsr

When true, a Graph Analytical View (GAV/CSR) that is READY (with no pending overlay changes) when the database closes cleanly writes its CSR to disk alongside a freshness certificate (the database’s last committed transaction id at build time). If nothing was committed to the database between that close and the next open, the certificate still matches and the persisted CSR is reused as-is instead of being rebuilt by a full graph scan. Any commit in between invalidates the certificate and falls back to the previous behavior: an async rebuild triggered on open. Set to false to disable persisting the CSR file (e.g. to avoid its disk footprint or the extra write at close). See Graph OLAP Engine. Since v26.9.1

Boolean

true

gavRestoreAwaitTimeout

Milliseconds database.open() blocks waiting for Graph Analytical Views (GAV/CSR) restored from persisted definitions to reach READY before returning. 0 (default) does not wait: when no persisted CSR plausibly applies, the full rebuild is still triggered immediately in the background, but open() returns before it completes and queries issued right after run unaccelerated until it does; when a persisted CSR does plausibly apply (see gavPersistCsr), nothing is even started at open() time as of v26.9.1 - it is deferred to whichever query touches the view first (see Lazy Restore), so the fast path costs nothing for a session that never queries it. A positive value here forces the wait either way, trading a slower open() for the restored/rebuilt view being usable by the query that triggered the reopen. See Graph OLAP Engine

Long

0

graph.edgeAppendMerge

At commit, when the only conflict on an edge-list page is concurrent in-chunk edge appends (which commute), re-apply the appends on top of the newer page version instead of failing the whole transaction with a retryable conflict. Removes the retry storm on super-node (hot vertex) edge insertion. See Super-Nodes. Since v26.7.2

Boolean

true

graph.edgeListInitialChunkSize

Size in bytes of the first chunk of a vertex’s edge list. Each further chunk doubles the previous one up to 8192, so the space a vertex allocates is the sum of that series - a smaller first chunk does not necessarily use less space, it just takes more chunks (each with its own header) to reach the same capacity. The best value follows the degree distribution: around 128 suits an average degree near 10, the default suits very sparse graphs, and above degree 100 the setting barely matters. Values below 32 are clamped. See Lightweight Edges. Since v26.8.1

Integer

64

graph.supernodeThreshold

Approximate number of edges (per vertex, per direction) after which the vertex’s edge list is promoted to the striped super-node layout, spreading further appends over multiple files so concurrent insertions on the same hot vertex do not contend. Forward-incompatible on first use: promotion writes a new record type, so once any vertex promotes the database can no longer be opened by releases older than v26.8.1; promotion is one-way. Iteration order on promoted vertices is approximate (newest-generation-first) instead of strict reverse-insertion. 0 disables promotion entirely (databases stay fully readable by older releases). See Super-Nodes. Since v26.8.1

Integer

4096

graph.supernodeStripes

Number of stripes (separate edge-list files) a super-node’s edge list is spread over at promotion. The stripes are hosted in a per-type bucket pool of this many files, created once per type at its first promotion (types without super-nodes cost no files). Write parallelism saturates at the number of concurrent writers, so values beyond the CPU cores rarely help. Values below 2 disable promotion entirely. Recorded per vertex at promotion time. See Super-Nodes. Since v26.8.1

Integer

16

gremlin.engine

Gremlin engine to use. By default the auto setting uses the legacy groovy engine in case parameters are set, otherwise, the new native java is preferred. If you have compatibility issues with gremlin statements that use lambdas or in general, switch to the groovy one

String

auto

gremlin.timeout

Default timeout for gremlin commands (in ms)

Long

8000

indexCompactionMinPagesSchedule

Minimum number of mutable pages for an index to be schedule for automatic compaction. 0 = disabled

Integer

10

indexCompactionRAM

Maximum amount of RAM to use for index compaction, in MB

Long

300

initialPageCacheSize

Initial number of entries for page cache

Integer

65535

vectorIndex.graphBuildCacheSize

Maximum number of vectors to cache in memory during HNSW graph building. Higher values speed up construction but use more RAM. RAM usage = cacheSize × (dimensions × 4 + 64) bytes. 0 (the default) sizes it automatically: an index whose vectors live in the documents (no quantization, or PRODUCT) caches the whole set when it fits vectorIndex.graphBuildCacheMaxHeapPercent, because every cache miss costs a record read; an inline-quantized index (INT8/BINARY) reads a miss straight from an index page and keeps a small bound instead. Setting an explicit value opts out of that auto-sizing

Integer

0

vectorIndex.graphBuildCacheMaxHeapPercent

Maximum share of the JVM heap the auto-sized graph-build cache may use. Only applies when vectorIndex.graphBuildCacheSize is left at 0. A corpus larger than this budget still builds: the cache evicts instead of holding everything. Measured against the heap currently available rather than against -Xmx, so a rebuild holding the old graph resident asks for less rather than the same. Values above 90 are clamped to 90

Integer

25

vectorIndex.searchCacheSize

Maximum number of vectors kept in the per-index search cache. The cache is shared by every query on the index and survives across queries, so a working set that fits stays resident instead of being re-read from the documents (or from the quantized index pages) on every beam-search hop. RAM usage = cacheSize × (dimensions × 4 + 64) bytes. 0 (the default) sizes it automatically from the number of indexed vectors, capped by vectorIndex.searchCacheMaxHeapPercent. -1 disables the cache entirely

Integer

0

vectorIndex.searchCacheMaxHeapPercent

Upper bound, as a percentage of the JVM heap currently available rather than of -Xmx, on the RAM an automatically sized per-index search cache may use (see vectorIndex.searchCacheSize). Ignored when the cache size is set explicitly. Values above 90 are clamped to 90

Integer

25

vectorIndex.locationCacheSize

Maximum number of vector locations to cache in memory per vector index. Set to -1 for unlimited. Each entry uses ~56 bytes. Recommended: 100000 for datasets with 1M+ vectors

Integer

-1

vectorIndex.prefilterMaxSelectivity

Maximum fraction of an index’s live vectors that a query’s RID allow-list may cover and still resolve the allow-list to its ordinals and score them directly, instead of paying for a Bits-filtered HNSW graph walk that gets more expensive, not less, as the allow-list narrows (a filter is only checked once a node is popped from the search beam, so a very selective filter can make the walk expand trying to fill k instead of shrinking). Applies to plain k-NN search and to groupBy search; see vectorIndex.prefilterApproximateMaxSelectivity for the separate threshold the PQ-approximate (zero-disk-I/O) search path uses. Set to 0 to always use the graph walk. Since v26.9.1

Float

0.2

vectorIndex.prefilterApproximateMaxSelectivity

The vectorIndex.prefilterMaxSelectivity threshold, but for PQ-approximate (zero-disk-I/O) vector search. Kept as a separate, lower setting because PQ scores a candidate from in-memory codes roughly an order of magnitude cheaper than the exact path’s page/document read, so its graph walk stays the cheaper option down to a narrower allow-list than the exact path’s. Set to 0 to always use the graph walk. Since v26.9.1

Float

0.05

vectorIndex.mutationsBeforeRebuild

Number of mutations (inserts/updates/deletes) before rebuilding the HNSW graph index. Higher values reduce rebuild cost but may return slightly stale results. Recommended: 50-200 for read-heavy, 200-500 for write-heavy workloads

Integer

100

vectorIndex.rebuildGraphRatio

Fraction of the current graph size that must accumulate as pending mutations before the HNSW graph is rebuilt, on top of the absolute vectorIndex.mutationsBeforeRebuild floor. A rebuild always reindexes the whole graph, so a fixed count makes it cost O(index size) for every few new vectors and turns bulk ingestion quadratic; scaling the threshold with the graph amortizes rebuilds instead. Vectors waiting for the next rebuild stay exactly searchable in memory meanwhile, so a higher ratio trades a slightly longer per-query scan of those vectors for far less rebuild CPU. Set to 0 to use only the absolute threshold

Float

0.2

vectorIndex.maxPendingMutations

Ceiling on the threshold computed from vectorIndex.rebuildGraphRatio. Set to 0 for no ceiling. Being a fixed count, it stops scaling once the ratio-derived threshold reaches it (at the defaults, from 250,000 vectors upward), so past that point the same absolute per-query scan cost lands on an index of any size. vectorIndex.maxDeltaScanRatio is the size-independent bound and is the setting to reach for when query latency, rather than rebuild frequency, is what needs protecting

Integer

50000

vectorIndex.maxDeltaScanRatio

How much work a query may spend scanning vectors written since the last graph rebuild, as a multiple of the work its graph search already does, before a rebuild is triggered to absorb them. Those vectors are answered by a straight scan, so that part of a query grows with how many are waiting while the graph search it supplements grows only with the logarithm of the index size: at the default vectorIndex.maxPendingMutations the scan has been measured at four fifths of query time. The count-based settings cannot bound it, so this one is measured rather than assumed - ArcadeDB records how many nodes its graph searches actually visit and compares the waiting vectors against that. 1.0 lets the scan cost about as much as the search. Lower it for latency-sensitive read-heavy workloads, raise it to rebuild less often, set 0 to disable. A rebuild is only triggered once the scans have also cost as much as the rebuild will, so the extra rebuild CPU this can introduce is bounded by the query CPU it removes. Because it is evaluated when queries run, a write-only workload never triggers it. Reported by the index statistics as deltaScanBudget, deltaScanWorkSinceRebuild and deltaScanWorkTarget. Since v26.9.1

Float

1.0

vectorIndex.inactivityRebuildTimeoutMs

Inactivity timeout in milliseconds before flushing buffered vectors and rebuilding the HNSW graph. When mutations exist but haven’t reached the rebuild threshold, a timer starts after the last mutation. On a graph under 1,000 vectors the rebuild is cheap and fires for any pending mutation count; on a larger graph it only fires once pending mutations reach at least 10% of the effective rebuild threshold, so a single stray insert does not force a full graph rebuild. The size compared against is the number of vectors the index holds, not the part of the graph the session has loaded, so an ingest-then-idle process that never queries is gated the same way. Set to 0 to disable. Recommended: 10000-30000 for low-volume ingestion

Integer

15000

vectorIndex.rebuildMaxHeapPercent

Share of the currently available heap that an online vector graph rebuild’s estimated peak footprint may occupy before the rebuild is deferred instead of attempted. An online rebuild keeps the old graph resident so searches keep working and pays for a full new build’s working set on top of it, so it costs roughly 1.7x what building the same corpus from nothing costs; with no gate it simply attempts the rebuild and dies with an OutOfMemoryError when it does not fit. A deferred cycle is not lost: pending vectors stay exactly searchable through the in-memory delta buffer, so the cost is a longer delta scan per query rather than wrong or missing results, and the deferral is logged and counted as rebuildsDeferredForMemory in the index statistics. Applies to online rebuilds only - a first build, a rebuild on close, REBUILD INDEX and COMPACT INDEX are never declined. Values above 90 are clamped to 90. Set to 0 to disable the gate. Since v26.9.1

Integer

90

vectorIndex.rebuildDeferralCooldownMs

Minimum time in milliseconds before another online vector graph rebuild may be attempted after one was deferred for lack of heap (see vectorIndex.rebuildMaxHeapPercent). A deferral does not consume the pending mutations that triggered it - only a successful build does - so without a cooldown the next search re-triggers it immediately, and since a search checks on every query a large heap-constrained index would spawn a rebuild thread, take the JVM-wide rebuild permit and log a warning once per query. A rebuild that completes clears the cooldown. Set to 0 to retry on the next trigger. Since v26.9.1

Integer

30000

maxPageRAM

Maximum amount of pages (in MB) to keep in RAM

Long

4096

pageFlushQueue

Size of the asynchronous page flush queue

Integer

512

pageSnapshotEnabled

When true (the default), a full backup, an HA database verify and an HA snapshot ship read a point-in-time image served from a page-level copy-on-write shadow, so writers keep running at full speed for the duration. When false, or when the shadow exceeds pageSnapshotMaxSize, they fall back to freezing the data files instead, which throttles every writer until the operation finishes

Boolean

true

pageSnapshotMaxRAM

Memory budget in MB for the copy-on-write shadow of a single point-in-time window. The shadow only holds the pages modified while the window is open, once each, so a short backup on a moderately busy database often never touches the disk at all. Beyond this budget the shadow spills to a scratch file (see pageSnapshotSpillPath)

Long

64

pageSnapshotMaxSize

Hard limit in MB (memory plus spill file) on a single copy-on-write shadow before the window is abandoned and its consumer falls back to freezing the data files. The default -1 sizes the limit automatically when the window opens: the smaller of the size the page files occupy at that instant - which the shadow provably cannot exceed - and half the space free on the spill volume, but never less than pageSnapshotMaxRAM, since that part of the budget never touches the disk. Set a positive value to pin an absolute limit in MB, or 0 for no limit

Long

-1

pageSnapshotSpillPath

Directory for the scratch file a copy-on-write shadow spills into once pageSnapshotMaxRAM is exhausted. Empty (the default) uses the database directory, where the shadow competes for space with the very files it is protecting. The file is pure scratch: created on demand, deleted when the window closes, and never read by recovery

String

polyglotCommand.timeout

Default timeout for polyglot commands (in ms)

Long

10000

queryMaxHeapElementsAllowedPerOp

Maximum number of elements (records) allowed in a single query for memory-intensive operations (eg. ORDER BY in heap). If exceeded, the query fails with an OCommandExecutionException. Negative number means no limit.This setting is intended as a safety measure against excessive resource consumption from a single query (eg. prevent OutOfMemory)

Long

500000

sqlStatementCache

Maximum number of parsed statements to keep in cache

Integer

300

txRetries

Number of retries in case of MVCC exception

Integer

3

txRetryDelay

Maximum amount of milliseconds to compute a random number to wait for the next retry. This setting is helpful in case of high concurrency on the same pages (multi-thread insertion over the same bucket

Integer

100

txWAL

Uses the WAL

Boolean

true

txWalFiles

Number of concurrent files to use for tx log. 0 (default) = available cores

Integer

(machine dependent)

txWalFlush

Flushes the WAL on disk at commit time. It can be 0 = no flush, 1 = flush without metadata and 2 = full flush (fsync). In production server mode, this is automatically set to 1 if not explicitly configured. See concepts/transactions.adoc#wal-flush-durability

Integer

0

typeDefaultBuckets

Default number of buckets to create per type

Integer

1

Gremlin

GremlinServer:com.arcadedb.server.gremlin.GremlinServerPlugin

gRPC

gRPC:com.arcadedb.server.grpc.GrpcServerPlugin

MongoDB

MongoDB:com.arcadedb.mongo.MongoDBProtocolPlugin

Postgres

Postgres:com.arcadedb.postgres.PostgresProtocolPlugin

Prometheus

Prometheus:com.arcadedb.metrics.prometheus.PrometheusMetricsPlugin

Redis

Redis:com.arcadedb.redis.RedisProtocolPlugin

grpc.enabled

Start the gRPC server when the plugin is registered. Set to false to keep the plugin loaded but the listener stopped

Boolean

true

grpc.port

Port for the standard gRPC server. A registered server setting since v26.9.1 (so it is also resolved from environment variables and listed in the settings API), because HA reads it to advertise a peer’s gRPC endpoint - see the grpc field of arcadedb.ha.serverList

Integer

50051

grpc.host

Host/interface to bind to

String

0.0.0.0

grpc.mode

Server mode: standard, xds, or both

String

standard

grpc.xds.port

Port for the xDS server (used when grpc.mode is xds or both)

Integer

50052

grpc.tls.enabled

Enable TLS for the gRPC server

Boolean

false

grpc.tls.cert

Path to the TLS certificate chain file (required when grpc.tls.enabled=true)

String

(none)

grpc.tls.key

Path to the TLS private key file (required when grpc.tls.enabled=true)

String

(none)

grpc.maxMessageSize

Maximum inbound message size, in MB

Integer

100

grpc.reflection.enabled

Enable the gRPC server reflection service (used by tools such as grpcurl)

Boolean

true

grpc.health.enabled

Enable the standard gRPC health-checking service

Boolean

true

grpc.compression.enabled

Advertise support for message compression

Boolean

true

grpc.compression.force

Force compression on all outbound messages

Boolean

false

grpc.compression.type

Compression algorithm used when grpc.compression.force=true

String

gzip