Configuring a repository

Before you start adding or changing the parameter values, we recommend planning your repository configuration and familiarizing yourself with what each of the parameters does, what data structures GraphDB supports, and what configuration values are optimal for your setup.

Configure a repository through the GraphDB Workbench

This section describes the fields on the configuration form that you use to create a new repository and to edit the settings of an existing repository. To edit the settings of an existing one, click the Edit repository icon-fa-pen icon on the Repositories screen.

  • Repository ID: Unique identifier for the repository. The ID must contain only letters (a-z, A-Z), numbers (0-9), and the characters ‘-‘ and ‘_’. This is a required field when creating a new repository. When editing the configuration of an existing one, click the edit icon icon-fa-pen shown with this field to change the repository ID value. )

  • Repository description: Human readable description of the repository.

  • Read-only: Prevents any edits to the repository’s data.

  • Encrypted: Makes the repository data encrypted using the Encryption at rest mechanism.

    Warning

    • To create an encrypted repository, you must first provide GraphDB with a Master Key.

    • You cannot change whether a repository is encrypted or not. Once a repository has been created encrypted, the encryption cannot be removed, and vice versa — an unencrypted repository cannot be encrypted.

    • This may also affect the Backup and restore procedures.

Inference and Validation

  • Ruleset: Sets of axiomatic triples, consistency checks and entailment rules, that determine the applied semantics with a PIE file. When creating a repository, a Custom ruleset button with this field lets you upload a custom ruleset.

Indexing

  • Entity ID size: Select 32-bit or 40-bit to define the bit size of internal IDs used to index entities such as URIs, blank nodes, literals, and RDF* embedded triples. Use 40-bit ID only if you expect more than 2 billion unique RDF values.

    Note

    Using 40-bit entity IDs requires a GraphDB Enterprise or Standard license.

    • Enable context index: Builds an additional Context-Predicate-Subject-Object index to boost the SPARQL query performance of queries with GRAPH, FROM, and FROM NAMED clauses.

    • Enable predicate list index: Enables the mappings from an entity (subject or object) to its predicates; this can significantly speed up queries that use wildcard predicate patterns.

    • Enable full-text search (FTS) index: Enables the use of Full-text search with this repository.

  • FTS indexes to build (comma delimited): List of languages that should have a specific index with appropriate analyzer for full-text search. Possible values: default, iri, ar, bg, bn, br, ca, ja, ko, zh, ku, cz, da, de, el, en, es, et, eu, fa, fi, fr, ga, gl, hi, hu, hy, id, it, lt, lv, ne, nl, no, pt, ro, ru, sr, sv, ta, te, th, tr.

  • FTS index for xsd:string literals: The index in which the string literals (xsd:string) are indexed. Possible values are: none, default or a two-letter language code.

  • FTS index for full-text indexing of IRIs: The index in which the IRIs are indexed for full-text search. Possible values are: none, default or a two-letter language code.

Queries and Updates

  • Query timeout (seconds): Sets the number of seconds after which the evaluation of a query will be terminated; values less than or equal to zero mean no limit. The Throw exception on query timeout checkbox with this field sets the repository to throw a QueryEvaluationException when the duration of a query execution exceeds the timeout parameter.

  • Limit query results: Sets the number of seconds after which the evaluation of a query will be terminated. Values less than or equal to zero mean no limit.

  • Restart repository: (Only displayed when editing an existing repository’s configuration) checking this indicates that when you click the form’s Save button you want the repository restarted with the new settings applied.

Note

If you need a repository with SHACL validation enabled , you must enable this option at configuration time. SHACL validation cannot be enabled after the repository has been created.

Edit a repository configuration using Workbench

Some of the parameters you specify at repository creation time can be changed at any point.

  1. On the Repositories screen, click the Edit icon icon-fa-pencil next to a repository to display the form that lets you edit the repository’s parameters. The documentation page Configure a repository through the GraphDB Workbench describes the fields on this form.

  2. Restart the repository for the changes to take effect.

Configure a repository programmatically

Tip

GraphDB uses an RDF4J configuration template to configure its repositories. RDF4J keeps the repository configurations with their parameters modeled in RDF. Therefore, in order to create a new repository, RDF4J needs such an RDF file.

To configure a new repository programmatically:

  1. Fill in the graphdb.ttl configuration template that can be found in the /configs/templates directory of the GraphDB distribution. The parameters are described in the Configuration parameters section. Here is an example:

    # Example RDF4J configuration template for a GraphDB repository named "wines"

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rep: <http://www.openrdf.org/config/repository#> .
@prefix sail: <http://www.openrdf.org/config/sail#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<#wines> a rep:Repository;
    rep:repositoryID "wines";
    rep:repositoryImpl [
        rep:repositoryType "graphdb:SailRepository";
        <http://www.openrdf.org/config/repository/sail#sailImpl> [
            <http://www.ontotext.com/config/graphdb#base-URL> "http://example.org/owlim#";
            <http://www.ontotext.com/config/graphdb#check-for-inconsistencies> "false";
            <http://www.ontotext.com/config/graphdb#defaultNS> "";
            <http://www.ontotext.com/config/graphdb#disable-sameAs> "true";
            <http://www.ontotext.com/config/graphdb#enable-context-index> "false";
            <http://www.ontotext.com/config/graphdb#enable-fts-index> "false";
            <http://www.ontotext.com/config/graphdb#enable-literal-index> "true";
            <http://www.ontotext.com/config/graphdb#enablePredicateList> "true";
            <http://www.ontotext.com/config/graphdb#entity-id-size> "32";
            <http://www.ontotext.com/config/graphdb#entity-index-size> "10000000";
            <http://www.ontotext.com/config/graphdb#fts-indexes> ("default" "iri");
            <http://www.ontotext.com/config/graphdb#fts-iris-index> "none";
            <http://www.ontotext.com/config/graphdb#fts-string-literals-index> "default";
            <http://www.ontotext.com/config/graphdb#imports> "";
            <http://www.ontotext.com/config/graphdb#in-memory-literal-properties> "true";
            <http://www.ontotext.com/config/graphdb#query-limit-results> "0";
            <http://www.ontotext.com/config/graphdb#query-timeout> "0";
            <http://www.ontotext.com/config/graphdb#read-only> "false";
            <http://www.ontotext.com/config/graphdb#repository-type> "file-repository";
            <http://www.ontotext.com/config/graphdb#ruleset> "rdfsplus-optimized";
            <http://www.ontotext.com/config/graphdb#storage-folder> "storage";
            <http://www.ontotext.com/config/graphdb#throw-QueryEvaluationException-on-timeout>
            "false";
            sail:sailType "graphdb:Sail"
        ]
    ];
    rdfs:label "" .

  2. Use the RDF4J API to load the configuration. See Create a repository for more information.

Configuration parameters

This is a list of all repository configuration parameters. Some of the parameters can be changed (effective after a restart), some cannot be changed (the change has no effect) and others need special attention once a repository has been created, as changing them will likely lead to inconsistent data (for example, unsupported inferred statements, missing inferred statements, or inferred statements that cannot be deleted).

Parameter name

Description

Default value

base-URL

Specifies the default namespace for the main persistence file. Non-empty namespaces are recommended, because their use guarantees the uniqueness of the anonymous nodes that may appear within the repository.
none
Can be changed.
check-for-inconsistencies

Enables or disables the mechanism for consistency checking. If this parameter is true, consistency checks are defined in the rule file and applied at the end of every transaction. If an inconsistency occurs while committing a transaction, the whole transaction will be rolled back. See Consistency checks for more information.
false
Can be changed.

defaultNS

Default namespaces corresponding to each imported schema file, separated by semicolons. The number of namespaces must be equal to the number of schema files from the imports parameter described below. Example: graphdb:defaultNS "http://www.w3.org/2002/07/owl#;http://example.org/"

Warning: This parameter cannot be set via a command line argument.
<empty>
Cannot be changed.
disable-sameAs

Enables or disables the owl:sameAs optimization. See Optimization of owl:sameAs for more information.
true
Can change in the UI depending
enable-context-index

Possible value: true, where GraphDB will build and use the context index. See Context index for more information.
false
Can be changed.
enable-literal-index

Enables or disables the use of a literal index. The literal index is always built as data is loaded or modified. This parameter only affects whether the index is used during query answering. See Literal index for more information.
true
Can be changed.
enablePredicateList

Enables or disables mappings from an entity (subject or object) to its predicates; enabling it can significantly speed up queries that use wildcard predicate patterns. See Predicate lists for more information.
true
Can be changed.
enable-fts-index

Enables or disables the full-text search index. In general, searching is performed via SPARQL queries that use a pattern like this:

?value onto:fts (query index limit)

See Simple full-text search index for more information.
false
Can be changed.
fts-indexes

Comma-delimited list of languages that should have a specific index with an appropriate analyzer for full-text search. See Simple full-text search index for more information.

Possible values: default, iri, ar, bg, bn, br, ca, ja, ko, zh, ku, cz, da, de, el, en, es, et, eu, fa, fi, fr, ga, gl, hi, hu, hy, id, it, lt, lv, ne, nl, no, pt, ro, ru, sr, sv, ta, te, th, tr
default, iri
Can be changed.
fts-string-literals-index

The index in which the string literals (xsd:string) are indexed. See Simple full-text search index for more information.

Possible values: none, default, or a 2-letter language code.
default
Can be changed.
fts-iris-index

The index in which the IRIs are indexed for full-text search. See Simple full-text search index for more information.

Possible values: none, default, or a 2-letter language code.
none
Can be changed.
entity-id-size

Defines the bit size of internal IDs used to index entities. This parameter can be left at its default value. However, if you are using very large datasets containing over 2 31 entities, set this parameter to 40. Be aware that this can only be set when instantiating a new repository, and that converting an existing repository from 32 to 40-bit entity widths is not possible.

Using 40-bit entity IDs requires a GraphDB Enterprise or Standard license.

Possible values: 32 and 40.
32
Cannot be changed.
entity-index-size

Defines the initial size of the entity hash table index entries. The bigger the size, the fewer the collisions in the hash table, and the faster the entity retrieval. The entity hash table will adapt to the number of stored entities once the number of collisions passes a critical threshold. See Sample memory configuration for more information.

Warning

The entity-index-size parameter is deserialized as an integer and cannot exceed Integer.MAX_VALUE (2,147,483,647). Setting a value beyond this limit will result in an error, preventing the repository from being created.

10,000,000
imports
Tip: Schema files can be either a local path name, e.g., ./ontology/myfile.rdf or a URL, e.g., http://www.w3.org/2002/07/owl.rdf. If this parameter is used, the default namespace for each imported schema file must be provided using the defaultNS parameter.

A list of schema files that will be imported at startup. All statements found in these files will be loaded in the repository and will be treated as read-only. The serialization format is determined by the file extension:

  • .brf => BinaryRDF

  • .n3 => N3

  • .nq => N-Quads

  • .nq => N-Quads

  • .nt => N-Triples

  • .owl => RDF/XML

  • .rdf => RDF/XML

  • .rdfs => RDF/XML

  • .trig => TriG

  • .trix => TriX

  • .ttl => Turtle

  • .xml => TriX

Example: graphdb:imports "./ont/owl.rdfs;./ont/ex.rdfs"
none
Cannot be changed.
in-memory-literal-properties

Enables or disables caching of the literal languages and data types. If the caching is on and the entity pool is restored from persistence, but there is no such cache available on disk, it is created after the entity pool initialization. See Caching literal language tags for more information.
true
Can be changed.

nonInterpretablePredicates

Semicolon-separated list of predicates (full URLs) that GraphDB will not try to process with the registered GraphDB plugins. (Predicates processed by registered plugins are often called “Magic” predicates.) This optimization will speed up the data loading by providing a hint that these predicates are not magic.

 
http://www.w3.org/2000/01/rdf-
schema#label;http://www.w3.org/
1999/02/22-rdf-syntax-ns#type;
http://www.ontotext.com/owlim/
ces#gazetteerConfig;http:
//www.ontotext.com/owlim/ces
#metadataConfig

query-limit-results

Sets the maximum number of results returned from a query after which the evaluation of a query will be terminated; values less than or equal to zero mean no limit.
0; (no limit)
Can be changed.
query-timeout

Sets the number of seconds after which the evaluation of a query will be terminated; values less than or equal to zero mean no limit. See Automatically prevent long running queries for more information.
0; (no limit)
Can be changed.

read-only

In this mode, no modifications to the data or namespaces are allowed.

Possible value: true, puts the repository in read-only mode.
false
Can be changed.

repository-type

In this mode, no modifications to the data or namespaces are allowed.

Possible values: file-repository, weighted-file-repository.
file-repository
Cannot be changed.
ruleset
Tip: Hints on optimizing GraphDB’s rulesets.

Sets of axiomatic triples, consistency checks and entailment rules, which determine the applied semantics. See Rulesets for more information.

Possible values: empty, rdfs, owl-horst, owl-max, and owl2-rl, and their optimized counterparts rdfs-optimized, owl-horst-optimized, owl-max-optimized, and owl2-rl-optimized. A custom ruleset is chosen by setting the path to its rule file .pie.
Warning: This parameter needs special attention.

rdfsplus-optimized
storage-folder

Specifies the folder where the index files will be stored. See Data storage for more information.
none
Can be changed.

throw-QueryEvaluationException-on-timeout

Controls whether GraphDB returns only partial results, or an error and no results upon reaching a timeout.

Possible values: true; if set, a QueryEvaluationException is thrown when the duration of a query execution exceeds the timeout parameter and a log entry is made. When this is set to false, GraphDB returns the partial results received prior to the query termination and no log entry is made. See Automatically prevent long running queries for further details.
false
Can be changed.

Namespaces defined for the repository

Under Setup ‣ Namespaces in the GraphDB Workbench you can view and manipulate the RDF namespaces and prefixes for the active repository. Each GraphDB repository contains the following predefined prefixes:

Prefix

IRI

Description

gn:

http://www.geonames.org/ontology#

The GeoNames Ontology makes it possible to add geospatial semantic information to the Word Wide Web. Over 11 million geonames toponyms have a unique URL with a corresponding RDF web service.

owl:

http://www.w3.org/2002/07/owl#

As with RDFS, properties in OWL are used to link things together. OWL provides a rich and complex vocabulary for saying things about these links. It allows you to construct some fairly complex, but useful, relationships among classes.

path:

http://www.ontotext.com/path#

GraphDB extends SPARQL with the Graph Path Search features that allow you to not only find complex relationships between resources but also explore them and use them as filters to identify graph patterns.

rdf:

http://www.w3.org/1999/02/22-rdf-syntax-ns#

The RDF Schema for the RDF vocabulary terms in the RDF Namespace, defined in RDF 1.1 Concepts and Abstract Syntax.

rdfs:

http://www.w3.org/2000/01/rdf-schema#

A general-purpose language for representing simple RDF vocabularies on the Web, RDF Schema is a semantic extension of RDF. It provides mechanisms for describing groups of related resources and the relationships between these resources.

wgs:

http://www.w3.org/2003/01/geo/wgs84_pos#

GraphDB provides support for two-dimensional geospatial data that uses the WGS84 Geo Positioning RDF vocabulary (World Geodetic System 1984).

xsd:

http://www.w3.org/2001/XMLSchema#

The standard set of datatypes available to RDF.

fn:

http://www.w3.org/2005/xpath-functions

XPATH functions on datatypes.

ofn:

http://www.ontotext.com/sparql/functions/

Beside the standard SPARQL functions operating on numbers, GraphDB offers several additional functions, allowing users to do more mathematical operations.

spif:

http://spinrdf.org/spif#

SPIN provides meta-modeling capabilities that allow users to define their own SPARQL functions and query templates. SPIN makes a library of common functions available.

afn:

http://jena.apache.org/ARQ/function#

GraphDB supports Jena simple functions analogs.

list:

ttp://jena.apache.org/ARQ/list#

GraphDB supports Jena list functions analogs.

agg:

http://jena.apache.org/ARQ/function/aggregate#

GraphDB supports Jena aggregate functions analogs.

apf:

http://jena.apache.org/ARQ/property#

GraphDB supports Jena property functions analogs.

geof:

http://www.opengis.net/def/function/geosparql/

GeoSPARQL defines a vocabulary for representing geospatial data in RDF, and it defines an extension to the SPARQL query language for processing geospatial data.

geoext:

http://rdf.useekm.com/ext#

On top of the standard GeoSPARQL functions, GraphDB adds a few useful extensions based on the USeekM library.

omgeo:

http://www.ontotext.com/owlim/geo#

Used by an Ontotext geospatial extension.

math:

http://www.w3.org/2005/xpath-functions/math

XPATH namespace used for some mathematical functions.

map:

http://www.w3.org/2005/xpath-functions/map

XPATH namespace used for some functions that manipulate maps.

array:

http://www.w3.org/2005/xpath-functions/array

XPATH namespace used for some functions that manipulate arrays.

rep:

http://www.openrdf.org/config/repository#

Parameter namespace for an RDF4J repository configuration consisting of a single RDF subject of type rep:Repository.

sr:

http://www.openrdf.org/config/repository/sail#

Parameter namespace for an RDF4J SailRepository repository implementation, which is the main implementation for direct access to a local RDF database.

sail:

http://www.openrdf.org/config/sail#

Parameter namespace for the Sail configuration.

graphdb:

http://www.ontotext.com/config/graphdb#

Reserved GraphDB repository configuration namespace.

Reconfigure a repository

Once a repository is created, you can change some parameters, either by editing it in the Workbench or by setting a global override for a given property.

Note

When you change a repository parameter, you need to restart GraphDB for the changes to take effect.

Using Workbench

To edit a repository parameter in the GraphDB Workbench, go to Setup ‣ Repositories and click the Edit icon for the repository whose parameters you want to edit.

Global overrides

It is also possible to override a repository parameter for all repositories by setting a configuration or system property. See Engine properties for more details.

Rename a repository

Using Workbench

You can rename a repository on the screen where you edit the repository configuration. This will update all locations in the Workbench where the repository name is used.

Change location settings

You can enable or disable the sending of anonymous statistics to Graphwise. The default setting depends on the GraphDB license that you are using. With GraphDB Free, it is enabled by default, and with GraphDB Standard and Enterprise, it is disabled by default.

To enable or disable it manually, click the Repository screen’s gear icon icon-fa-gear that has the tooltip Edit common settings for these repositories.

_images/usage-statistics-icon.png

This displays the Settings dialog box, which includes a “more info” link that adds additional information to the dialog box as shown here:

_images/usage-statistics.png

Repository Caching Mechanism

You can also automatically limit the number of active repositories in your GraphDB instance through the Repository Caching Mechanism. The Repository Caching Mechanism will automatically shut down repositories based on an LRU (least-recently-used) policy. The mechanism can be configured on a timeout basis (time elapsed since last access to the repository) or a quantity basis (limiting the number of active repositories). Both of those can be enabled and configured individually of each other.

Once a repository has been shut down, it can be activated again as usual.

Note

  • The Repository Caching Mechanism is defined on a system level and is the same for all repositories. For more information, see the System properties documentation.

  • The mechanism will never shut down repositories with active repository connections. If more repositories are active than the caching size permits it will wait until a repository with 0 active connections becomes available to be shut down.

Limiting the number of active repositories

You can control the number of active repositories using the graphdb.max.active.repositories system property. By default, GraphDB has a cache limit of 100 active repositories. Once the limit is reached, the Repository Caching Mechanism will start shutting down the least recently used repositories until all of them can fit in the cache.

To disable this policy, set the value of graphdb.max.active.repositories to 0.

Set a timeout for active repositories

The Repository Caching Mechanism can start shutting down repositories that have not been accessed in a defined timeout period. By default the time policy is disabled with a default value of 0.

The timeout can be defined through the graphdb.repository.expiry.after.minutes system property, which takes a value in minutes.