Configuring a repository¶

Plan a repository configuration¶

To plan your repository configuration, check out the following sections:

• sizing-guidelines.
• disk-space-requirements.
• Configuration parameters.
• How the template works.
• GraphDB data structures.
• Configure Java heap memory.
• Configure Entity pool memory.

Configure a repository through the GraphDB Workbench¶

To configure a new repository, complete the repository properties form.

Edit a repository¶

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

1. Click the edit icon next to a repository to edit it.
2. Restart GraphDB for the changes to take effect.

Configure a repository programmatically¶

To configure a new repository programmatically:

1. Fill in the .ttl configuration template that can be found in the /templates folder of the GraphDB distribution. The parameters are described in the Configuration parameters section.

   # RDF4J configuration template for a GraphDB Free repository
   
   @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
   @prefix rep: <http://www.openrdf.org/config/repository#>.
   @prefix sr: <http://www.openrdf.org/config/repository/sail#>.
   @prefix sail: <http://www.openrdf.org/config/sail#>.
   @prefix owlim: <http://www.ontotext.com/trree/owlim#>.
   
   [] a rep:Repository ;
       rep:repositoryID "graphdb-test" ;
       rdfs:label "GraphDB Free repository" ;
       rep:repositoryImpl [
           rep:repositoryType "graphdb:FreeSailRepository" ;
           sr:sailImpl [
               sail:sailType "graphdb:FreeSail" ;
   
               owlim:base-URL "http://example.org/graphdb#" ;
               owlim:defaultNS "" ;
               owlim:entity-index-size "10000000" ;
               owlim:entity-id-size  "32" ;
               owlim:imports "" ;
               owlim:repository-type "file-repository" ;
               owlim:ruleset "rdfs-plus-optimized" ;
               owlim:storage-folder "storage" ;
   
               owlim:enable-context-index "false" ;
   
               owlim:enablePredicateList "true" ;
   
               owlim:in-memory-literal-properties "true" ;
               owlim:enable-literal-index "true" ;
   
               owlim:check-for-inconsistencies "false" ;
               owlim:disable-sameAs  "false" ;
               owlim:query-timeout  "0" ;
               owlim:query-limit-results  "0" ;
               owlim:throw-QueryEvaluationException-on-timeout "false" ;
               owlim:read-only "false" ;
               owlim:nonInterpretablePredicates "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" ;
           ]
       ].
   

2. Update the RDF4J SYSTEM repository with this configuration by issuing the following on the command line (all in one line) replacing the filename (config.ttl), URL to the remote server’s SYSTEM directory (http://server1:7200/repositories/SYSTEM) and a unique context in which to put the repository configuration (http://example.com#g1):

   curl -X POST -H "Content-Type:application/x-turtle" -T config.ttl
     -d graph=http://example.com#g1
     http://server1:7200/repositories/SYSTEM/rdf-graphs/service
   

3. Update the SYSTEM repository with a single statement to indicate that the unique context is an instance of sys:RepositoryContext:

   curl -X POST -H "Content-Type:application/x-turtle"
     -d "<http://example.com#g1> a <http://www.openrdf.org/config/repository#RepositoryContext>."
     http://server1:7200/repositories/SYSTEM/statements
   

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 (e.g., unsupported inferred statements, missing inferred statements, or inferred statements that can not be deleted).

• base-URL
• defaultNS
• entity-index-size
• entity-id-size
• imports
• repository-type
• ruleset
• storage-folder
• enable-context-index
• enablePredicateList
• index-in-memory-literal-properties
• enable-literal-index
• check-for-inconsistencies
• disable-sameAs
• query-timeout
• query-limit-results
• throw-QueryEvaluationException-on-timeout
• read-only
• Non-interpretable predicates

base-URL (Can be changed)

Description: 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.

Default value: none

defaultNS (Cannot be changed)

Description: Default namespaces corresponding to each imported schema file separated by semicolon and the number of namespaces must be equal to the number of schema files from the imports parameter.

Default value: <empty>

Example: owlim:defaultNS "http://www.w3.org/2002/07/owl#;http://example.org/owlim#".

Warning

This parameter cannot be set via a command line argument.

entity-index-size (Cannot be changed by the user once initially set)

Description: Defines the initial size of the entity hash table index entries. The bigger the size, the less 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.

Default value: 10000000

entity-id-size (Cannot be changed)

Description: Defines the bit size of internal IDs used to index entities (URIs, blank nodes and literals). In most cases, this parameter can be left to its default value. However, if very large datasets containing more than 2 ³¹ entities are used, set this parameter to 40. Be aware that this can only be set when instantiating a new repository and converting an existing repository from 32 to 40-bit entity widths is not possible.

Default value: 32

Possible values: 32 and 40

imports (Cannot be changed)

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

• .brf => BinaryRDF
• .n3 => N3
• .nq => N-Quads
• .nt => N-Triples
• .owl => RDF/XML
• .rdf => RDF/XML
• .rdfs => RDF/XML
• .trig => TriG
• .trix => TriX
• .ttl => Turtle
• .xml => TriX

repository-type (Cannot be changed)

Default value: file-repository

Possible values: file-repository, weighted-file-repository.

ruleset (Needs special attention)

Description: Sets of axiomatic triples, consistency checks and entailment rules, which determine the applied semantics.

Default value: rdfs-plus-optimized

Possible values: empty, rdfs, owl-horst, owl-max and owl2-rl and their optimised 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.

Tip

Hints on optimising GraphDB’s rulesets.

storage-folder (Can be changed)

Description: specifies the folder where the index files will be stored.

Default value: none

enable-context-index (Can be changed)

Default value: false

Possible value: true, where GraphDB will build and use the context index.

enablePredicateList (Can be changed)

Description: Enables or disables mappings from an entity (subject or object) to its predicates; switching this on can significantly speed up queries that use wildcard predicate patterns.

Default value: false:

in-memory-literal-properties (Can be changed)

Description: Turns caching of the literal languages and data-types on and off. 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 initialisation.

Default value: false

enable-literal-index (Can be changed)

Description: Enables or disables the storage. The literal index is always built as data is loaded/modified. This parameter only affects whether the index is used during query-answering.

Default value: true

check-for-inconsistencies (Can be changed)

Description: Turns the mechanism for consistency checking on and off; consistency checks are defined in the rule file and are applied at the end of every transaction, if this parameter is true. If an inconsistency is detected when committing a transaction, the whole transaction will be rolled back.

Default value: false

disable-sameAs (Needs special attention)

Description: Enables or disables the owl:sameAs optimisation.

Default value: false

query-timeout (Can be changed)

Description: 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.

Default value: 0; (no limit);

query-limit-results (Can be changed)

Description: 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.

Default value: 0; (no limit);

throw-QueryEvaluationException-on-timeout (Can be changed)

Default value: false

Possible value: true; if set, a QueryEvaluationException is thrown when the duration of a query execution exceeds the time-out parameter.

read-only (Can be changed)

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

Default value: false

Possible value: true, puts the repository in to read-only mode.

Non-interpretable predicates

Description: “Colon-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.”

Default value: 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

Configure GraphDB memory¶

Configure Java heap memory¶

The following diagram offers a view of the memory use by the GraphDB structures and processes:

To specify the maximum amount of heap space used by a JVM, use the -Xmx virtual machine parameter.

The Xmx value should be about 2/3 of the system memory. For example, if a system has 8GB total of RAM and 1GB is used by the operating system, services, etc. and 1GB by the entity pool and the hash maps, as they are off heap, ideally, the JVM that hosts the application using GraphDB should have a maximum heap size of 6GB and can be set using the JVM argument: -Xmx6g.

-Dgraphdb.epool.onheap=true

Reconfigure a repository¶

Once a repository is created, it is possible to change some parameters, either by editing it in the Workbench, by changing the configuration in the SYSTEM repository or by setting a global override for a given property.

PREFIX sys:  <http://www.openrdf.org/config/repository#>
PREFIX sail: <http://www.openrdf.org/config/repository/sail#>
PREFIX onto: <http://www.ontotext.com/trree/owlim#>
DELETE { GRAPH ?g {?sail ?param ?old_value } }
INSERT { GRAPH ?g {?sail ?param ?new_value } }
WHERE {
  GRAPH ?g { ?rep sys:repositoryID ?id . }
  GRAPH ?g { ?rep sys:repositoryImpl ?impl . }
  GRAPH ?g { ?impl sys:repositoryType ?type . }
  GRAPH ?g { ?impl sail:sailImpl ?sail . }
  GRAPH ?g { ?sail ?param ?old_value . }
  FILTER( ?id = "repo_id" ) .
  FILTER( ?param = onto:enable-context-index ) .
  BIND( "true" AS ?new_value ) .
}

Rename a repository¶