Database Configuration

This page discusses configuring a Stardog database’s options, otherwise known as a database’s metadata.

Page Contents

Overview
Getting and Setting Database Options
Database Options

Overview

To administer a Stardog database, some configuration options must be set at creation time; others may be changed subsequently and some may never be changed. All config options have sensible defaults (except for the database name), so you don’t have to twiddle any of the knobs till you really need to.

A database’s configuring options are often referred to as its metadata. In fact, in Stardog’s security model, the metadata resource type refers to this.

Getting and Setting Database Options

To configure an existing database via the CLI, you use the metadata-get and metadata-set commands.

Often times, a database must be set to offline status before most configuration parameters may be changed. These properties are known as being “mutable” as explained just below. Hence, the normal routine is to set the database offline, change the parameters, and then set the database online. All of these operations may be done programmatically from CLI tools, such that they can be scripted in advance to minimize downtime.

Below in the database options section, each option’s definition has an attribute “mutability”. The value set here describes a property’s ability to change values. We use the following terms to describe an option’s mutability.

Immutable: Properties that are immutable can only be set at database creation time.
Mutable: Properties that are mutable can only be set while the database is offline. See the db offline CLI command to offline a database.
Freely Mutable: Properties that are freely mutable can be set at any time. It does not matter if the database is online or offline.

You can get some information about a database by running the following command:

$ stardog-admin metadata get my_db_name

This will return all the metadata stored about the database, including the values of configuration options used for this database instance. If you want to get the value for a specific option then you can run the following command:

$ stardog-admin metadata get -o icv.enabled my_db_name

Similarly, to set a database configuration option we can use the metadata set CLI command:

$ stardog-admin metadata set -o icv.enabled=false -- my_db_name

Database Options

The following sections describe available configuration options in Stardog.

Database

Core database configuration options.

`database.archetypes`

Mutability: Mutable
Default
Java API: DatabaseOptions.ARCHETYPES
Description: The name of one or more database archetypes, used to associate ontologies and constraints with new databases. See the docs for instructions to create your own archetype.

`database.connection.timeout`

Mutability: Freely Mutable
Default: 10m
Java API: DatabaseOptions.CONNECTION_TIMEOUT
Description: The amount of time a connection to the database can be open, but inactive, before being automatically closed to reclaim the resources. The following unit suffixes are available: "ms" for milliseconds, "s" for seconds, "m" for minutes, and "h" for hours.

`database.name`

Mutability: Immutable
Default
Java API: DatabaseOptions.NAME
Description: A database name, the legal value of which is given by the regular expression [A-Za-z]{1}[A-Za-z0-9_-]

`database.namespaces`

Mutability: Freely Mutable
Default: owl, rdf, rdfs, so, stardog, xsd
Java API: DatabaseOptions.NAMESPACES
Description: The default namespaces for the database. Legal input is a comma-separated list of <prefix>=<namespace> values.

`database.online`

Mutability: Immutable
Default: true
Java API: DatabaseOptions.ONLINE
Description: Whether or not the database is online

`database.type`

Mutability: Immutable
Default: user
Java API: DatabaseOptions.TYPE
Description: Specifies the database as either user or system.

`edge.properties`

Mutability: Immutable
Default: false
Java API: DatabaseOptions.EDGE_PROPERTIES
Description: Option for enabling edge properties that allows RDF statements to appear as subjects of RDF statements (aka RDF*).

`graph.aliases`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.GRAPH_ALIASES
Description: Configuration option to enable or disable support for named graph aliases

`label.properties`

Mutability: Mutable
Default: rdfs:label
Java API: DatabaseOptions.LABEL_PROPERTIES
Description: Comma-separated list of property IRIs which may be used by the platform to look up entity labels by entity IRIs. By default it's only rdfs:label but properties from SKOS or other schema can be added. The order of the properties in the list reflect their rank when labels from different properties are present for an entity IRI.

`literal.comparison.extended`

Mutability: Freely Mutable
Default: true
Java API: DatabaseOptions.EXTENDED_COMPARISON
Description: Controls whether query evaluation will use extended literal comparison. If enabled, literals of different datatypes are first compared based on their string values and then based on the string value of their datatypes.

`literal.language.normalization`

Mutability: Immutable
Default: DEFAULT
Java API: DatabaseOptions.LANGUAGE_NORMALIZATION
Description: Configuration option for determining the normalization algorithm for the langauge tags of literals.

`media.enabled`

Mutability: Freely Mutable
Default: false
Java API: DatabaseOptions.MEDIA_ENABLED
Description: Option for whether or not to render media, such as URL hyperlinks in Stardog Applications. By default, media will not be rendered. Use additional caution before enabling this property when using public or unknown data sources.

`preserve.bnode.ids`

Mutability: Immutable
Default: true
Java API: DatabaseOptions.PRESERVE_BNODE_IDS
Description: Determines how the Stardog parser handles bnode (blank node) identifiers that may be present in RDF input. If this property is enabled, parsing and data loading performance are improved; but the other effect is that if distinct input files use (randomly or intentionally) the same bnode identifier, that bnode will point to one and the same node in the database. If you have input files that use explicit bnode identifiers, and more than one of those files may use the same bnode identifiers, and you don't want those bnodes to be smushed into a single node in the database, then this configuration option should be disabled. Note that, this option has no effect for input files using the JSON-LD syntax. JSON-LD API specification requires all bnode identifiers from the input document to be mapped to new identifiers so they cannot be preserved in the database.

`progress.monitor.enabled`

Mutability: Freely Mutable
Default: true
Java API: DatabaseOptions.PROGRESS_MONITOR_ENABLED
Description: When enabled, the progress of various tasks will be printed in the server log.

`strict.parsing`

Mutability: Immutable
Default: true
Java API: DatabaseOptions.STRICT_PARSING
Description: Controls whether Stardog parses RDF strictly (true, the default) or loosely (false). Setting this to "false" will allow, for example, integer literals with leading zeros.

`system.graphs`

Mutability: Mutable
Default: default
Java API: DatabaseOptions.SYSTEM_GRAPHS
Description: Specifies the IRIs of named graphs which contain system data and could be hidden from user queries by excluding the <tag:stardog:api:context:system> alias. By default, the alias is expanded to three graphs: the stored query graph for Voicebox-enabled databases, the graph which stored alias definitions, and the BI/SQL table mapping graph.

Full-Text Search

Options for configuring full-text search indexing and querying. Read more about semantic search in Stardog.

`search.default.limit`

Mutability: Freely Mutable
Default: -1
Java API: SearchOptions.SEARCH_DEFAULT_LIMIT
Description: Specify the default limit on the number of results returned from a full-text search (-1 returns all results). This only limits the number of results returned from the Lucene full-text index, not from its containing query.

`search.default.query.operator`

Mutability: Mutable
Default: OR
Java API: SearchOptions.SEARCH_DEFAULT_QUERY_OPERATOR
Description: Specify the Lucene operator (AND/OR) to use when the search query has multiple keywords

`search.enabled`

Mutability: Mutable
Default: false
Java API: SearchOptions.SEARCHABLE
Description: Enables the full-text (unstructured) search index for the database; important for Text Search applications.

`search.index.batch.size`

Mutability: Mutable
Default: 1000
Java API: SearchOptions.SEARCH_INDEX_BATCH_SIZE
Description: Specifies the number of Lucene documents that are written to search index in one batch

`search.index.compute.norm`

Mutability: Mutable
Default: false
Java API: SearchOptions.INDEX_COMPUTE_NORM
Description: Option to specify that value lengths (norms) should be computed and indexed. This is required for document length to influence scoring rank.

`search.index.contexts.excluded`

Mutability: Mutable
Default: true
Java API: SearchOptions.SEARCH_CONTEXTS_EXCLUDED
Description: Option to specify if the collection of contexts in named graphs is going to be leveraged as either excluded or included for literals to be indexed.

`search.index.contexts.filter`

Mutability: Mutable
Default
Java API: SearchOptions.SEARCH_CONTEXTS_FILTER
Description: Option to specify the collection of named graphs to be excluded or included for lexical search indexing. If search.index.contexts.excluded is set to true, the literals in the named graphs specified by this option will be excluded from the lexical search index. Otherwise only the literals from the specified named graphs will be indexed. This option has no effect if search.enabled is not enabled.

`search.index.datatypes`

Mutability: Mutable
Default: xsd:string, rdf:langString
Java API: SearchOptions.INDEX_DATATYPES
Description: Option to specify the datatypes for which to index literals in Lucene. Literals with other datatypes will not be accessible via full-text search.

`search.index.properties.excluded`

Mutability: Mutable
Default
Java API: SearchOptions.INDEX_PROPERTIES_EXCLUDED
Description: Option to specify the excluded properties for literals not to be indexed in Lucene. Literals with these properties cannot be evaluated for indexing.

`search.index.properties.included`

Mutability: Mutable
Default
Java API: SearchOptions.INDEX_PROPERTIES_INCLUDED
Description: Option to specify the only properties for literals to be indexed in Lucene. Please note that if search.index.properties.excluded option is set, this option will have no effect.

`search.index.stopwords`

Mutability: Mutable
Default
Java API: SearchOptions.INDEX_STOPWORDS
Description: Option to specify the list of the stopwords while indexing. The list of string is to be converted to a CharArraySet data structure of Lucene.

`search.index.token.filters`

Mutability: Mutable
Default
Java API: SearchOptions.INDEX_TOKEN_FILTERS
Description: A sequence of token filter classes. Classes must be implementations of org.apache.lucene.analysis.TokenFilter. Filters will be applied in the order listed. Class names must be qualified by package unless existing in the `org.apache.lucene.analysis` package. The `StopFilter`, if specified, will used the value of the `search.index.stopwords` property.

`search.index.vacuum`

Mutability: Freely Mutable
Default: false
Java API: SearchOptions.USE_VACUUMING
Description: This option controls how the full-text index is optimized as a part of database optimization. If set to true, Stardog will use the vacuuming technique to purge text literals which were previously been removed from the data also from the full-text index. The default value is false which means that the index will be rebuilt from scratch. This property is ignored in two cases: if search.optimize=true is explicitly supplied as an argument to 'db optimize' command, or if the index is in a dirty state i.e. it may lack some literals occurring in the data (this normally should not happen unless full-text index has not completed successfully).

`search.index.wordbreak.chars`

Mutability: Mutable
Default
Java API: SearchOptions.WORD_BREAK_CHARS
Description: A set of characters which are used to break words. Whitespace is also included

`search.label.relative.threshold`

Mutability: Mutable
Default: 0.8
Java API: SearchOptions.LABEL_RELATIVE_THRESHOLD
Description: Specify the relative threshold used for the Entity Label Service. The Entity Label Service uses full-text search to find the entities with a given label. This is the relative threshold value that will be used in these cases overriding the default relative threshold. See the description for the option search.relative.threshold for more details.

`search.lexical.enabled`

Mutability: Mutable
Default: true
Java API: SearchOptions.SEARCH_LEXICAL
Description: Enables lexical search (default implementation of full-text search).

`search.page.size`

Mutability: Freely Mutable
Default: 100000
Java API: SearchOptions.SEARCH_PAGE_SIZE
Description: Specify the page size used for iteration over results from the full-text index. A page is held in memory, so this count should NOT be large.

`search.reindex.cache.size`

Mutability: Freely Mutable
Default: 16384
Java API: SearchOptions.REINDEX_CACHE_SIZE
Description: Option to specify the cache size of literals that is used for checking if a literal is indexed before.

`search.reindex.tx`

Mutability: Freely Mutable
Default: true
Java API: SearchOptions.SEARCH_REINDEX_IN_TX
Description: Whether literals added during a transaction are automatically indexed. If this flag is set to 'false', then full-text search queries will return incomplete results until the index is rebuilt.

`search.relative.threshold`

Mutability: Mutable
Default: 0.0
Java API: SearchOptions.RELATIVE_THRESHOLD
Description: Specify the default relative threshold for full-text search. The value should be a floating number between 0.0 and 1.0 to indicate all matching literals should be returned. A relative threshold of 0.0 means only the full-text matches with highest score will be returned. In general, if the top score for a query is {@code S} then only the matches with score higher than or equal to `S * relativeThreshold` will be returned. The relative threshold value can be overridden in the full-text search query with the `fts:relativeThreshold` parameter.

`search.semantic.enabled`

Mutability: Mutable
Default: false
Java API: SearchOptions.SEARCH_SEMANTIC
Description: Enables semantic search.

`search.semantic.index.contexts.filter`

Mutability: Mutable
Default
Java API: SearchOptions.SEARCH_SEMANTIC_CONTEXTS_FILTER
Description: Option to specify the collection of named graphs to be excluded or included for semantic search indexing. If search.index.contexts.excluded is set to true, the literals in the named graphs specified by this option will be excluded from the semantic search index. Otherwise only the literals from the specified named graphs will be indexed. This option has no effect if semantic search is not enabled via the search.semantic.enabled option.

`search.semantic.model`

Mutability: Mutable
Default
Java API: SearchOptions.SEARCH_SEMANTIC_MODEL
Description: URL to a language model that will be used to generate embeddings vectors and store them in Lucene index. The default value is an empty string which means the default semantic model shipped with Stardog will be used.

`search.wildcard.search.enabled`

Mutability: Freely Mutable
Default: false
Java API: SearchOptions.LEADING_WILDCARD_SEARCH_ENABLED
Description: Enable support to query the Lucene full-text search index with leading wildcards.

GraphQL

Options for the GraphQL query interface. Read more about Stardog’s support for GraphQL.

`graphql.auto.schema`

Mutability: Freely Mutable
Default: false
Java API: GraphQLOptions.AUTO_SCHEMA
Description: Enables automatic generation of the default GraphQL schema if one has not been created by the user.

`graphql.auto.schema.source`

Mutability: Freely Mutable
Default: owl
Java API: GraphQLOptions.AUTO_SCHEMA_SOURCE
Description: Specifies the input source to use for generating the default GraphQL schema automatically.

`graphql.data.graphs`

Mutability: Freely Mutable
Default: stardog:context:local
Java API: GraphQLOptions.DATA_GRAPHS
Description: Specifies which graphs will be queried by default via GraphQL queries. The default value (tag:stardog:api:context:local) is to query all local graphs (default or named). Use the special graph tag:stardog:api:context:all to query all local graphs plus the virtual graphs. Multiple graphs or graph aliases can be used as the option value.

`graphql.default.limit`

Mutability: Freely Mutable
Default: -1
Java API: GraphQLOptions.DEFAULT_LIMIT
Description: The maximum number of top-level objects a GraphQL query can return. The argument "first" can be used within queries to limit results as well.

`graphql.result.memory.limit`

Mutability: Freely Mutable
Default: 100M
Java API: GraphQLOptions.RESULT_MEMORY_LIMIT
Description: The maximum number of heap memory a GraphQL result can use. GraphQL query results are created fully in memory before they are sent back to the client. This limit ensures query results will not use too much memory causing server to run out of memory. GraphQL queries are translated to SPARQL queries and the amount of memory the SPARQL query will use during execution is controlled by the query.memory.limit option.

Index

Options for configuring database indices.

`index.bulk.load.sst.txlimit`

Mutability: Freely Mutable
Default: 495000
Java API: IndexOptions.TX_BULK_LOAD_ADAPTIVE_THRESHOLD
Description: Threshold estimated input size at which the bulk loading mechanism will be considered for transactional updates.

`index.bulk.load.tx.threshold`

Mutability: Freely Mutable
Default: 4000000
Java API: IndexOptions.TX_BULK_LOAD_HARD_THRESHOLD
Description: Threshold of actual number of quads, where Stardog use bulk loading. Max effective value is 8388608.

`index.differential.enable.limit`

Mutability: Mutable
Default: 500000
Java API: IndexOptions.DIFF_INDEX_MIN_LIMIT
Description: NOTE: Not used in Stardog v7+. The minimum number of statements in the Stardog database before differential indexes are used.

`index.differential.merge.limit`

Mutability: Mutable
Default: 20000
Java API: IndexOptions.DIFF_INDEX_MAX_LIMIT
Description: NOTE: Not used in Stardog v7+. The size in number of RDF statements before the differential indexes are merged to the main indexes.

`index.literals.canonical`

Mutability: Immutable
Default: true
Java API: IndexOptions.CANONICAL_LITERALS
Description: Specify that non-string typed literals are canonicalized in the database. Improves query and loading performance, but does change literal values to a canonical form. For example, "1"^^xsd:byte is canonicalized to "1"^^xsd:integer. Set this option to false if you require literals to be exactly as specified, rather than canonicalized. The default value is 'true'. note that, this value can only be set at database creation time and cannot be changed at a future time.

`index.lucene.mmap`

Mutability: Mutable
Default: true
Java API: DatabaseOptions.LUCENE_MMAP
Description: Enables memory-mapping in lucene indices (e.g., search, spatial).

`index.statistics.cache.capacity`

Mutability: Mutable
Default: 1024
Java API: IndexOptions.CARDINALITY_CACHE_CAPACITY
Description: The max capacity for the query pattern cardinality cache that is shared across queries to the same database.

`index.statistics.chains.enabled`

Mutability: Freely Mutable
Default: true
Java API: IndexOptions.STATISTICS_CHAINS_ENABLED
Description: If true, Stardog will pre-compute the number of times frequent binary chains occur in the data and will use that information for query optimization.Could be disabled for very large or very complex datasets. Changes to this option will take effect the next time statistics is recomputed.

`index.statistics.characteristic.limit`

Mutability: Freely Mutable
Default: 10000
Java API: IndexOptions.STATISTICS_CHARACTERISTIC_SETS_LIMIT
Description: The max number of characteristic sets computed as a part of the statistical summary of the database. More diverse datasets may require a higher number for more accurate query planning. The downside is higher memory footprint and slower planning

`index.statistics.enable_active_graph`

Mutability: Mutable
Default: true
Java API: IndexOptions.STATS_ENABLE_ACTIVE_GRAPH
Description: If true, Stardog will adjust the cardinality estimation for a query with based on the size of the active graph. Could be disabled for databases with few large named graphs with non-overlapping data.

`index.statistics.object_joins.enabled`

Mutability: Freely Mutable
Default: true
Java API: IndexOptions.STATISTICS_OBJECT_JOIN_ENABLED
Description: If true, Stardog will pre-compute the object join cardinalities for pairs of properties in the dataset. This information is used for query optimization.Could be disabled for very large or very complex datasets. Changes to this option will take effect the next time statistics is recomputed.

`index.statistics.on_db_create`

Mutability: Immutable
Default: Sync
Java API: IndexOptions.STATISTICS_ON_DB_CREATION
Description: Determines whether and how selectivity statistics is computed when a database is bulk loaded. By default it's computed synchronously.

`index.statistics.predicate.threshold`

Mutability: Freely Mutable
Default: 0.001
Java API: IndexOptions.STATISTICS_RARE_PREDICATE
Description: If a certain predicate occurs in less than this share of all triples in the data, Stardog will not maintain extended statistics for that predicate.

`index.statistics.range.sample.size`

Mutability: Freely Mutable
Default: 100
Java API: IndexOptions.STATISTICS_RANGE_SAMPLE_SIZE
Description: The number of elements from the range of a property that are examined to classify the property as an object or data property. Used for query optimization.

`index.statistics.sketch.capacity`

Mutability: Freely Mutable
Default: 100000000
Java API: IndexOptions.STATISTICS_SKETCH_CAPACITY
Description: The max number of objects that can be added to a sketch data structure before a new sketch is created

`index.statistics.update.automatic`

Mutability: Freely Mutable
Default: true
Java API: IndexOptions.AUTO_STATS_UPDATE
Description: Determines whether statistics are maintained automatically. When set to "true", Stardog will decide when to update statistics as the database is modified through additions and removals and update statistics as needed. If this option is set to "false", Stardog will never update the statistics regardless of how much the database is updated.

`index.statistics.update.blocking.ratio`

Mutability: Freely Mutable
Default: 0.0
Java API: IndexOptions.STATS_UPDATE_BLOCKING_RATIO
Description: Once the ratio of updated triples to database size goes over this limit statistics computation will be performed synchronously within the transaction instead of a background thread. Setting this option to a non-positive number (<= 0) will disable blocking updates.

`index.statistics.update.min.size`

Mutability: Freely Mutable
Default: 10000
Java API: IndexOptions.STATS_UPDATE_DB_MIN_SIZE
Description: Minimum number of triples that should be in the database for statistics to be updated automatically

`index.statistics.update.ratio`

Mutability: Freely Mutable
Default: 0.1
Java API: IndexOptions.STATS_UPDATE_RATIO
Description: Ratio of updated triples to the number of triples in the database that triggers the automatic statistics computation in a background thread

`index.writer.merge.limit`

Mutability: Mutable
Default: 1000
Java API: IndexOptions.INDEX_WRITER_MERGE_LIMIT
Description: Maximum number of triples to keep in memory for merging interleaving additions and removals while querying uncommitted state

Integrity Constraint Violations (ICV)

Options for validating data against constraints. Read more about using ICV constraints in Stardog.

`icv.active.graphs`

Mutability: Immutable
Default: stardog:context:local
Java API: ICVOptions.ICV_ACTIVE_GRAPHS
Description: Specifies which part of the database, in terms of named graphs, is checked with IC validation

`icv.consistency.automatic`

Mutability: Mutable
Default: false
Java API: ICVOptions.ICV_CONSISTENCY_AUTOMATIC
Description: Enables automatic ICV consistency check as part of transactions. Ensures that both reasoning consistencies and constraint violations are checked during ICV "Guard Mode" validation (with each commit). This is only effective when "icv.reasoning.enabled" is set to true.

`icv.enabled`

Mutability: Mutable
Default: false
Java API: ICVOptions.ICV_ENABLED
Description: Determines if all database mutations are subject to ICV. When enabled, each commit is inspected to ensure that the contents of the database are valid. Should a transaction attempt to commit invalid data, the commit will fail and the data will not be added/removed.

`icv.explanation.limit`

Mutability: Freely Mutable
Default: 1
Java API: ICVOptions.ICV_EXPLANATION_LIMIT
Description: The number of violations that will be computed and returned in the error message when guard mode is enabled. If the option is set to 0 no explanations will be computed and transaction failure will only indicate there was a violation without specifying which constraint failed.

`icv.reasoning.enabled`

Mutability: Mutable
Default: false
Java API: ICVOptions.ICV_REASONING_ENABLED
Description: Determines if reasoning is used during ICV.

`shacl.shape.graphs`

Mutability: Mutable
Default: stardog:context:local
Java API: ICVOptions.SHACL_SHAPE_GRAPHS
Description: The set of named graphs from which to read the SHACL shapes for validation. Only the shapes that are defined within these names graphs will be validated. By default the shapes in all the local named graphs will be used.

`shacl.targetClass.simple`

Mutability: Freely Mutable
Default: false
Java API: ICVOptions.SHACL_TARGET_CLASS
Description: If true, sh:targetClass will be evaluated based on rdf:type triples only, without following rdfs:subClassOf relations.

`shacl.violation.limit.shape`

Mutability: Mutable
Default: -1
Java API: ICVOptions.SHACL_VIOLATION_LIMIT_PER_SHAPE
Description: Limits the number of violation per shape. The default value is -1. This option is introduced for ease of readability of the report on the types of different violations.

Query

Options for configuring query execution behavior.

`query.all.graphs`

Mutability: Freely Mutable
Default: false
Java API: DatabaseOptions.QUERY_ALL_GRAPHS
Description: This option controls the behavior for answering queries that don't specify a dataset (FROM or FROM NAMED) in the query. In such cases, the SPARQL specification says that the query should be answered only using the information in default graph (no context). However, sometimes it is desirable to answer such queries using all the information in the database including the default graph and all named graphs. Setting this option to true changes the behavior of Stardog to do this. Queries that specify a dataset are not affected by this option.

`query.describe.strategy`

Mutability: Freely Mutable
Default: default
Java API: DatabaseOptions.QUERY_DESCRIBE_STRATEGY
Description: The default DESCRIBE query strategy for the database. Built-in strategies include "default", "cbd" and "bidirectional". See the docs for instructions to create your own describe strategy.

`query.dictionary.overflow.threshold`

Mutability: Freely Mutable
Default: 100000
Java API: DatabaseOptions.QUERY_DICTIONARY_SIZE_THRESHOLD
Description: Configuration option for the max number of entries in the query-local dictionary before a persistent data structure is used (which can spill data to disk)

`query.inline.sqs`

Mutability: Freely Mutable
Default: OPTIMIZER
Java API: DatabaseOptions.INLINE_STORED_QUERY
Description: Option to control how stored queries should be evaluated inside the Stored Query Service (SQS). If stored queries referenced in SQS are inlined into the parent query some additional optimizations might become possible especially for stored queries involving virtual graphs. But inlined stored queries inherit the dataset of the parent query and might return different results compared to being executed in isolation. Some queries, e.g. stored queries that use path queries or correlation, cannot be inlined at all. The setting `optimizer` allows the optimizer to perform inlining when it is safe and improves query performance. Using the option `always` could cause some SQS executions fail.

`query.log.enabled`

Mutability: Freely Mutable
Default: true
Java API: DatabaseOptions.QUERY_LOG_ENABLED
Description: If set to true, Stardog will log all queries executed against this database

`query.memory.exceeds.strategy`

Mutability: Freely Mutable
Default: SPILL_TO_DISK
Java API: DatabaseOptions.QUERY_MM_EXCEEDS_STRATEGY
Description: Configuration option for determining strategy for the query behaviour once memory limit reached

`query.memory.limit`

Mutability: Freely Mutable
Default: 9223372036854775807B
Java API: DatabaseOptions.QUERY_MEMORY_LIMIT
Description: Configuration option for determining the memory limit used by query

`query.plan.reuse`

Mutability: Freely Mutable
Default: ALWAYS
Java API: DatabaseOptions.QUERY_PLAN_REUSE
Description: The conditions under which a cached plan will be reused. "ALWAYS" and "NEVER" determine query plan reuse as you would expect. "CARDINALITY" instructs Stardog to reuse cached query plans for structurally equivalent queries if the cardinality estimations of scans are similar.

`query.term.equality.identity`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.QUERY_EQUALITY_IDENTITY
Description: If true, Stardog's query optimizer will interpret equality checks, like FILTER(?x = ?y), as if the variables range over IRIs or strings, i.e., each value can only be equal to itself. This is not true for certain numbers in SPARQL, for example, 1 is equal to 1.0. The default value is false, which is the spec-compliant behavior. Setting it to true can unlock additional optimizations for queries and rules with equality filters.

`query.timeout`

Mutability: Freely Mutable
Default: 5m
Java API: DatabaseOptions.QUERY_TIMEOUT
Description: Determines max execution time for query evaluation. This can also be overridden in a query's parameters. The following unit suffixes are available: "ms" for milliseconds, "s" for seconds, "m" for minutes, and "h" for hours.

`query.update.graph.diff`

Mutability: Freely Mutable
Default: true
Java API: DatabaseOptions.QUERY_UPDATE_GRAPH_DIFF
Description: Configuration option for determining the update procedure that will be used for SPARQL update queries ADD, COPY and MOVE

`query.update.timeout`

Mutability: Freely Mutable
Default: 10h
Java API: DatabaseOptions.QUERY_UPDATE_TIMEOUT
Description: Determines max execution time for SPARQL update query evaluation. This can also be overridden in a query's parameters. The following unit suffixes are available: "ms" for milliseconds, "s" for seconds, "m" for minutes, and "h" for hours.

`service.prefetch.threshold`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.SERVICE_PREFETCH_THRESHOLD
Description: The cardinality threshold for prefetching solutions from remote services. A negative value disables prefetching and with a value of Integer.MAX_VALUE (2147483647) prefetching is always enabled. If the estimated cardinality of a service is below the threshold, 10K solutions will be prefetched by default. The number of solutions to be prefetched can be customized with the `service.prefetch.limit` query hint.

`service.sparql.credentials.passthrough.regex`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.SPARQL_SERVICE_CREDENTIALS_PASSTHROUGH_REGEX
Description: Specifies SPARQL endpoints for which SERVICE calls are allowed to pass through current credentials.

`service.sparql.result.limit`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.SPARQL_SERVICE_RESULT_LIMIT
Description: Limits the number of results generated by SERVICE calls to SPARQL endpoints. A negative value means no limit.

Reasoning

Options for configuring reasoning. Read more about reasoning in Stardog.

`auto.schema.reasoning`

Mutability: Freely Mutable
Default: false
Java API: DatabaseOptions.AUTO_SCHEMA_REASONING
Description: Enables reasoning when automatically generating schemas from OWL. This setting will affect automatic schema generation for GraphQL (if graphql.auto.schema is enabled) and BI/SQL (if sql.schema.auto is enabled).

`reasoning.approximate`

Mutability: Mutable
Default: false
Java API: ReasoningOptions.APPROXIMATE
Description: Enables approximate reasoning. With this flag enabled Stardog will approximate an axiom that is outside the profile Stardog supports and normally ignored. For example, an equivalent class axiom might be split into two subclass axioms and only one subclass axiom is used.

`reasoning.classify.eager`

Mutability: Mutable
Default: true
Java API: ReasoningOptions.EAGER_CLASSIFY
Description: Perform schema classification eagerly when the schema is loaded. Classifying eagerly ensures subclass and equivalence queries between named classes can be answered with a simple lookup. However, if the schema is changing frequently then this option can be turned off so classification is performed only if necessary.

`reasoning.consistency.automatic`

Mutability: Mutable
Default: false
Java API: ReasoningOptions.CONSISTENCY_AUTOMATIC
Description: Enables automatic consistency checking as part of every query performed with reasoning enabled. If the underlying database did not change since the last consistency check, the check will not be performed.

`reasoning.domain.range.rule.optimization`

Mutability: Mutable
Default: true
Java API: ReasoningOptions.DOMAIN_RANGE_OPTIMIZATION
Description: Enables optimization to remove redundant type assertions from queries or rule bodies when types can be inferred from schema.org domainIncludes/rangeIncludes or rdfs:domain/rdfs:range declarations on properties. This can improve reasoning performance by reducing the number of triple patterns in a query or a rule body. WARNING: This option is not conformant with RDFS and OWL semantics because schema.org vocabulary has no semantic interpretation. Enabling this option may cause reasoning queries to return more results if the data does not satisfy the domain/range declarations. If the data conforms to the domain/range declarations then the query results will not change due to this optimization. To ensure this, domain optimization only applies when a property has exactly one domain, and range optimization only applies when a property has exactly one range.

`reasoning.precompute.non_empty.predicates`

Mutability: Freely Mutable
Default: true
Java API: ReasoningOptions.PRECOMPUTE_NON_EMPTY_TERMS
Description: If true, Stardog will pre-compute class and property names which have assertions in the data. That can speed-up reasoning but may slow things down when data changes often.

`reasoning.punning.enabled`

Mutability: Mutable
Default: false
Java API: ReasoningOptions.PUNNING_ENABLED
Description: Enables punning; the ability for an IRI to represent both a class and an individual.

`reasoning.rewrite.limit`

Mutability: Freely Mutable
Default: 10000
Java API: ReasoningOptions.REWRITE_LIMIT
Description: The maximum number of triple patterns that is allowed in a rewritten reasoning query. If the number of triple patterns in the rewritten query exceeds this limit the rewriting will be canceled and query execution will fail.

`reasoning.rewriting`

Mutability: Mutable
Default: PER_SCOPE
Java API: ReasoningOptions.REWRITING_STRATEGY
Description: Allows one to choose how query patterns are rewritten for reasoning: as a whole (per scope) or individually (per pattern).

`reasoning.sameas`

Mutability: Mutable
Default: OFF
Java API: DatabaseOptions.EQUALITY_REASONING
Description: Option to enable owl:sameAs reasoning. When this option is set to "ON", then the reflexive, symmetric, and transitive closure of owl:sameAs triples in the database are computed. When it is set to "FULL", then owl:sameAs inferences are computed based on schema axioms, such as functional properties. See the docs for more information.

`reasoning.schema.catalog.export.enabled`

Mutability: Freely Mutable
Default: true
Java API: DatabaseOptions.CATALOG_SCHEMA_EXPORT
Description: Specifies whether reasoning schemas of this database are copied to Data Catalog

`reasoning.schema.graphs`

Mutability: Freely Mutable
Default: stardog:context:schema
Java API: ReasoningOptions.SCHEMA_GRAPHS
Description: Determines which, if any, named graph or graphs contains the schema (ontology, "TBox") part of the data. The legal value is a comma-separated list of named graph identifiers. The default value is tag:stardog:api:context:schema.

`reasoning.schema.timeout`

Mutability: Freely Mutable
Default: 1m
Java API: ReasoningOptions.SCHEMA_REASONING_TIMEOUT
Description: Timeout for schema reasoning. If schema reasoning cannot be completed in the specified time then only RDFS reasoning will be performed for the schema which might yield incomplete answers for the schema queries. The timeout values specified as test be a positive integer followed by either letter 'h' (for hours), letter 'm' (for minutes), letter 's' (for seconds), or letters 'ms' (for milliseconds). Examples: '1h' for 1 hour, '5m' for 5 minutes, '90s' for 90 seconds, '500ms' for 500 milliseconds.

`reasoning.schema.versioning.enabled`

Mutability: Mutable
Default: false
Java API: ReasoningOptions.ENABLE_SCHEMA_VERSIONING
Description: Determines if the reasoner will track changes to triples in schema graphs. Enabling this option allows reasoner to invalidate its state only when one of the schema graphs is updated. If this option is not enabled the reasoner will invalidate its state whenever any named graph is updated which is wasteful because the exact same state will be recomputed. When this option is enabled schema graphs have to be regular named graph IRIs and wildcard graphs cannot be used as schema graphs.

`reasoning.schemas`

Mutability: Freely Mutable
Default
Java API: ReasoningOptions.SCHEMAS
Description: Option to specify the schemas and the named graphs that constitute each schema. The value is a comma-separated collection of schema=IRI pairs. There should be one pair for each named graph in a schema. The graphs for the default schema are set via the reasoning.schema.graphs option.

`reasoning.schemas.memory.count`

Mutability: Mutable
Default: 5
Java API: ReasoningOptions.SCHEMAS_MEMORY_COUNT
Description: Option to specify the number of schemas to keep in memory. There can be more schemas defined in the database but only this many schemas will be kept in memory and other schemas will be pulled into memory as queries are getting answered. If this limit is too high, the amount of memory used for schemas will increase and might cause memory problems. If it is too low then answering reasoning queries might slow down.

`reasoning.stride`

Mutability: Mutable
Default: false
Java API: ReasoningOptions.STRIDE
Description: If enabled, Stardog will use the new Stride reasoner based on Datalog. Some functionality could be unstable or missing.

`reasoning.type`

Mutability: Mutable
Default: SL
Java API: ReasoningOptions.REASONING_TYPE
Description: Specifies the reasoning type associated with the database, most corresponding to the OWL Profiles of the same name. The following reasoning types are available: RDFS (OWL 2 axioms allowed in RDF Schema), QL (OWL 2 QL axioms), RL (OWL 2 RL axioms), EL (OWL 2 EL axioms), SL (a combination of RDFS, QL, RL and EL axioms + user-defined rules) and NONE (disables reasoning). Any axiom outside the selected type will be ignored by the reasoner. This option has no effect if reasoning.stride is enabled. Support for DL reasoning type has been removed in version 9.0 and cannot be used ianymore.

`reasoning.virtual.graph.enabled`

Mutability: Freely Mutable
Default: true
Java API: ReasoningOptions.VIRTUAL_GRAPH
Description: Flag to enable reasoning over virtual graphs and SERVICE clauses.

SQL

Options for the BI/SQL server interface. Read more about BI/SQL in Stardog.

`sql.data.graphs`

Mutability: Freely Mutable
Default: stardog:context:all
Java API: SerfOptions.DATA_GRAPHS
Description: Specifies which graphs will be queried by default via SQL queries. The default value (tag:stardog:api:context:all) is to query all local graphs (default or named) plus any virtual graphs that might be defined. Setting this option to another value will mean any other graph will be ignored by the SQL queries. Use the special graph tag:stardog:api:context:local to query all local graphs but exclude virtual graphs. Multiple graphs or graph aliases can be used as the option value.

`sql.schema.auto`

Mutability: Mutable
Default: true
Java API: SerfOptions.AUTO_SCHEMA
Description: Enables automatic SQL schema generation when one does not exist in the database.

`sql.schema.auto.source`

Mutability: Mutable
Default: owl
Java API: SerfOptions.AUTO_SCHEMA_FORMAT
Description: Specifies the input source to use for generating the SQL schema automatically when one does not exist in the database.

`sql.schema.graph`

Mutability: Mutable
Default: stardog:sql:schema
Java API: DatabaseOptions.SQL_SCHEMA_GRAPH
Description: Specifies which named graph in the database is used to read SQL schema mapping.

Security

Options for authentication and access control. Read more about security in Stardog.

`security.masking.function`

Mutability: Freely Mutable
Default: "Insufficient privileges to view this value"
Java API: SecurityOptions.MASKING_FUNCTION
Description: SPARQL function to mask values of sensitive properties. There should be just one variable in there which will be replaced by actual sensitive nodes at query runtime.

`security.named.graphs`

Mutability: Freely Mutable
Default: false
Java API: SecurityOptions.NAMED_GRAPH_SECURITY_ENABLED
Description: If enabled, named graphs are an explicit resource type in Stardog’s security model.

`security.properties.sensitive`

Mutability: Freely Mutable
Default
Java API: SecurityOptions.SENSITIVE_PROPERTIES
Description: Comma-separated set of property IRIs to which access is granted explicitly

`security.properties.sensitive.groups`

Mutability: Freely Mutable
Default
Java API: SecurityOptions.SENSITIVE_PROPERTY_GROUPS
Description: Option to specify the sensitive property groups. The value is a collection of (group name, property IRI) pairs. A property that appears in at least one group is considered sensitive and requires explicit permission to be granted for read access. The property IRIs in the default group should be defined with the option security.properties.sensitive.

Spatial

Options for indexing and querying geospatial data. Read more about geospatial queries in Stardog.

`spatial.distance.precision`

Mutability: Freely Mutable
Default: 8
Java API: GeospatialOptions.SPATIAL_DISTANCE_PRECISION
Description: Specifies the precision used for the distance calculations. The value is the number of significant digits distances used to represent distances. Smaller numbers sacrifice precision for performance. The default is 8. A value of -1 can be provided to compute distances to the maximum precision.

`spatial.enabled`

Mutability: Mutable
Default: false
Java API: GeospatialOptions.SPATIAL_ENABLED
Description: Enables the geospatial search index for the database.

`spatial.error.percentage`

Mutability: Immutable
Default: 0.025
Java API: GeospatialOptions.SPATIAL_ERROR_PCT
Description: A measure of acceptable error of the shape as a fraction. The value roughly corresponds to the fraction of a shape’s approximate radius. This setting does not affect points which are always indexed at the configured maximum precision as specified by spatial.precision but will affect other shapes. The default value is 0.025 (%2.5) and the valid values are between 0 and 0.5 (50%). Increasing this value will improve query performance as less levels are used but results will be less accurate.

`spatial.features`

Mutability: Freely Mutable
Default: UNKNOWN
Java API: GeospatialOptions.FEATURES
Description: Internally used by the system to keep track of what geospatial features are used in the data.

`spatial.precision`

Mutability: Immutable
Default: 11
Java API: GeospatialOptions.SPATIAL_PRECISION
Description: Specifies the precision used for the indexing of geospatial data. The smaller the value, the less precision, but the better the performance of geospatial queries. The default value is 11 which yields sub-meter precision; a value of 8 will give a precision +/- 50m.

`spatial.remove.in.tx`

Mutability: Mutable
Default: true
Java API: GeospatialOptions.REMOVE_IN_TX
Description: If true, remove spatial features from the spatial index immediately within the transaction. Otherwise, spatial features are left in the index until a manual optimization command clear them. Setting this option to false improves update performances significantly but the results from the spatial index should be joined with the RDF index to exclude phantom spatial features from query results.

`spatial.result.limit`

Mutability: Freely Mutable
Default: 10000
Java API: GeospatialOptions.SPATIAL_RESULT_LIMIT
Description: Specify the default limit on the number of results returned from a geospatial query (-1 returns all results). This only limits the number of results returned from the geospatial index, not from its containing query.

`spatial.result.page_size`

Mutability: Mutable
Default: 100000
Java API: GeospatialOptions.SPATIAL_RESULT_PAGE_SIZE
Description: Specify the page size used for iteration over results from the spatial index. A page is held in memory, so this count should NOT be large.

`spatial.use.jts`

Mutability: Mutable
Default: false
Java API: GeospatialOptions.USE_JTS
Description: Use JTS (Java Topology Suite) to support more complex spatial structures such as polygons.

Transaction

Options for configuring transaction behavior and logging.

`transaction.commit.twophase`

Mutability: Freely Mutable
Default: false
Java API: DatabaseOptions.TX_COMMIT_2P
Description: Enables two phase commit protocol for the cluster (this option has no effect for the single node server). When this option is enabled all the nodes in the cluster will prepare the transaction in the first phase of the commit. This ensures all nodes complete time-consuming operations and only after that the second phase of the commit will start where the coordinator will send the commit command to the other nodes. Once a node completes the commit operation the effects of the transaction will be visible in query results. With this option enabled the period of time where nodes might return different results to queries will be minimized. This option is most useful for long transactions (e.g., transactions that take several minutes or more) where the commit time for each node might differ in a noticeable way without the additional commit phase. For short transactions, enabling this option will not provide visible benefits (especially if transactions complete under a second) and the overhead of the additional commit phase will result in increased transaction times.

`transaction.isolation`

Mutability: Mutable
Default: SNAPSHOT
Java API: DatabaseOptions.TRANSACTION_ISOLATION
Description: Configures isolation level for transactions

`transaction.logging`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.TRANSACTION_LOGGING
Description: Option for whether or not the database logs all transactions events to disk. The default when not in Cluster mode is "false", and when in Cluster mode the default is "true".

`transaction.logging.chunk.size`

Mutability: Mutable
Default: 1024
Java API: DatabaseOptions.TRANSACTION_LOGGING_CHUNK_SIZE
Description: Number of statements per chunk when writing to the transaction log

`transaction.logging.rotation.keep_backups`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.TRANSACTION_LOGGING_KEEP_ROTATED_BACKUP_FILES
Description: Determines whether we keep backups of the rotated log file

`transaction.logging.rotation.remove`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.TRANSACTION_LOGGING_ROTATION_REMOVE
Description: Determines whether the current log file will be rotated or removed (i.e., truncated)

`transaction.logging.rotation.size`

Mutability: Mutable
Default: 500M
Java API: DatabaseOptions.TRANSACTION_LOGGING_ROTATION_SIZE
Description: Determines the size at which the transaction log will be rotated. Accepts human-readable values (e.g., '500M', '1G') or byte values. When transaction.logging.use.rotated is enabled, total disk usage can be up to twice this value.

`transaction.logging.use.rotated`

Mutability: Mutable
Default: true
Java API: DatabaseOptions.TRANSACTION_LOGGING_USE_ROTATED
Description: Enables using rotated transaction log

`transaction.write.conflict.strategy`

Mutability: Immutable
Default: LAST_COMMIT_WINS
Java API: IndexOptions.WRITE_CONFLICT_STRATEGY
Description: Which conflict resolution strategy to use for this database. Write conflicts occur when two transactions attempt to modify the same statement inthe database simultaneously.

Virtual Graphs

Options for querying external data sources as RDF. Read more about virtual graphs in Stardog.

`local.iri.template.excludes`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.LOCAL_IRI_TEMPLATE_EXCLUDES
Description: The set of IRI templates representing the form of IRIs which may NOT be present in the subject position of triples in the local database. Used when optimizing queries including both the local database and virtual graphs. IRI templates use the same placeholder syntax as mappings (eg, `{field}`) but the field names are ignored. Templates included here should be used to indicate which IRIs are guaranteed not to be present and should be updated when that changes.

`local.iri.template.includes`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.LOCAL_IRI_TEMPLATE_INCLUDES
Description: The set of IRI templates representing the form of IRIs which may be present in the subject position of triples in the local database. Used when optimizing queries including both the local database and virtual graphs. IRI templates use the same placeholder syntax as mappings (eg, `{field}`) but the field names are ignored. Templates included here should be used to indicate which IRIs may be present and should be updated when that changes.

`virtual.transparency`

Mutability: Freely Mutable
Default: false
Java API: DatabaseOptions.VIRTUAL_TRANSPARENCY
Description: Determines the default dataset the database evaluates queries against; if true, the named graphs portion of the dataset will default to local named graphs and accessible virtual graphs; if false (the default), the named graphs portion of the dataset will be limited to local named graphs only.

Voicebox

Options for natural language query interface. Read more about Voicebox in Stardog.

`voicebox.enabled`

Mutability: Mutable
Default: false
Java API: DatabaseOptions.VOICEBOX_ENABLED
Description: If set to true, Stardog enables the Voicebox LLM-based features for this database

`voicebox.example.questions`

Mutability: Freely Mutable
Default
Java API: DatabaseOptions.VOICEBOX_EXAMPLE_QUESTIONS
Description: List of example questions to showcase in the Voicebox UI for this database. These example questions may or may not correspond to a natural language question associated with a stored query. This option can be set without enabling Voicebox but in that case it will have no effect.

`voicebox.preprocessors`

Mutability: Mutable
Default: default
Java API: DatabaseOptions.VOICEBOX_PREPROCESORS
Description: List of preprocessors that will be applied to the stored queries to canonicalize the query serialization. Preprocessors transform queries into a form that is more suitable for Voicebox. Using the 'default' value enables the default list of preprocessors. The value 'noop' can be used to disable preprocessing.

`voicebox.schema.size.limit`

Mutability: Mutable
Default: 1000000
Java API: DatabaseOptions.VOICEBOX_MAX_SCHEMA_SIZE
Description: The max size (in triples) of the schema size that allows Voicebox to be enabled on the database.Large schemas may require long vector indexing time and delay bringing the database online.This limit also applies to Voicebox example questions since their query strings are also vector indexed.

Overview
Getting and Setting Database Options
Database Options