config

How to configure graph schema.

Synopsis

schema.config().option(arg).[ set(value) | unset(value) | get() | exists() | describe() ]

Schema can be configured per graph using the config() command. An option and value can be set() or unset(). An option's value can be retrieved with the get() command. Whether or not the option is configured can be discovered with the exists() command. The describe() command returns a value if the option has been set manually.

Table 1. Graph-specific optionsGraph-specific options are preceded by `graph`. For example, `graph.schema_mode`.
Option argument	Setting Example	Description	Default
allow_scan	true	Setting to allow costly graph scan queries.	true
schema_mode	Production	Set mode to Production or Development.	Development
default_property_key_cardinality	multiple	Set the cardinality that will be used by default unless otherwise specified.	single
tx_autostart	true	Set whether transactions are started automatically or must be manually opened.	false

Table 2. TraversalSource-specific optionsTraversalSource-specific options are preceded by `graph.traversal_sources.*` where * must be a specified traversal source such as the graph traversal g. For example, `graph.traversal_sources.g.type`. The most common TraversalSource is the graph traversal g.
Option argument	Setting Example	Description	Default
evaluation_timeout	PT10S (10 seconds) or "1500 ms"	Maximum time to wait for a traversal to evaluate - this will override other system level settings for the current TraversalSource.	0 days
restrict_lambda	false	Prevent the use of lambdas with this TraversalSource. A particular traversal source can be identified.	true
type	read-only	Specify type of TraversalSource. A particular traversal source can be identified.	default

Important: Setting a timeout value greater than 1095 days (maximum integer) can exceed the limit of a graph session. Starting a new session and setting the timeout to a lower value can recover access to a hung session. This caution is applicable for all timeouts: evaluation_timeout, system_evaluation_timeout, analytic_evaluation_timeout, and realtime_evaluation_timeout

Table 3. Transaction-specific optionsTransaction-specific options are preceded by `graph.tx_groups.*` where * must be specified as a transaction group or `default`. For example, `graph.tx_groups.default.read_only` will make all transactions which aren't explicitly named `read_only`, whereas `graph.tx_groups.myTxGroup.read_only` would apply only to transactions which are given the group name *myTxGroup*.
Option	Setting Example	Description	Default
authenticated_user	test_user	The username to use as the current user for a transaction.	ANONYMOUS_USER
cache	false	Cache retrievals and data store calls within a transaction in transaction-level caches. This setting provides a restricted type of isolation within a transaction (concurrent modifications in other transactions aren't visible and result sets remain consistent between calls) and can improve performance at the expense of additional memory consumption.	true
deep_profiling	true	Enable CQL tracing for `profile()` in queries. Very costly profiling.	false
internal_vertex_verify	true	Set whether a transaction should verify that vertices for internally provided auto-generated vertex ids actually exist.	false
external_vertex_verify	false	Set whether a transaction should verify that vertices for externally provided user-defined vertex ids actually exist.	true
logged_batch	true	Use a logged batch when committing changes. This guarantees that all mutations will eventually occur at the expense of performance.	false
max_mutations	5000	The maximum number of vertices, properties and edges (cumulatively) that may be added or removed in a single transaction.	10000
max_profile_events	5	The maximum number of profiling events to report for an individual traversal step. Restricting the number of reported events makes output manageable, but can hide important information.	10
prefetch	true	Sets whether the query executor should asynchronously pre-fetch data based on its expected execution of the traversal prior to the data being requested. This can reduce transaction latency but can cause throughput to worse.	true
read_only	true	Set whether a transaction is read-only.	false
read_consistency	ALL	Specify the consistency level for read operations of a transaction.	ONE
single_thread	true	Set whether a transaction is only accessed by a single thread.	false
thread_bound	true	Set whether a transaction is bound to a particular thread.	false
transaction_timestamp		The timestamp at which all mutations of this transaction are persisted.	Instant.EPOCH
verify_unique	false	Set whether transactions should ensure that uniqueness constraints are enforced.	true
vertex_cache_size	4000	Maximum size of the transaction-level cache of recently-used vertices	20000l
vertex_dirty_size		This is a performance hint for write-heavy, performance-sensitive transactional workloads. If set, it should roughly match the median vertices modified per transaction.	32
write_consistency	ANY	Specify the consistency level for write operations of a transaction	QUORUM

Description

Configure a graph. Options can be set, unset, or get (retrieve the value).

Examples

Set the current graph to use the Development schema_mode:

schema.config().option('graph.schema_mode').set('Development')

Set the current graph to allow full graph scans in the currently aliased graph:

schema.config().option('graph.allow_scan').set('true')

To set restrict_lambda to FALSE in order to test lambda functions (only appropriate for non-production systems):

schema.config().option('graph.traversal_sources.g.restrict_lambda').set('FALSE')

To retrieve all traversal sources that have been set, use the get() command with the traversal source type option:

schema.config().option('graph.traversal_sources.*.type').get()

resulting in a list of values for the option that have been manually set:

REAL_TIME

indicating that a real-time evaluation timeout is set.

To verify that user-defined vertex ids exist during data loading, set the external_vertex_verify() option:

schema.config().option('graph.tx_groups.default.external_vertex_verify').set('TRUE')

If this setting is true, then a vertex will not be returned if it doesn't exist. However, if external_vertex_verify() is set to false, then a vertex will be returned even if the vertex does not exist given an id. Applications should ensure that vertices exist using the exists() method for expected behavior. The internal_vertex_verify() setting is similarly used for auto-generated vertex ids.

Set the default write consistency for all transactions to ALL in the currently aliased graph:

schema.config().option('graph.tx_groups.default.write_consistency').set('ALL')

Get the current write consistency for all transactions in the currently aliased graph:

schema.config().option('graph.tx_groups.default.write_consistency').get()

To confirm that an option setting has been set manually, use the exists() command:

schema.config().option('graph.tx_groups.default.write_consistency').exists()

This command will return:

true

if the setting has been set to a value, otherwise it returns false.

To enable CQL tracing during traversal query profiling, set the deep_profiling() option:

schema.config().option('graph.tx_groups.default.deep_profiling').set('TRUE')

To set schema settings at the time a graph is created, chain the options into the system.graph().create() command:

system.graph('food2').
  replication("{'class' : 'NetworkTopologyStrategy', 'dc1' : 3 }").  
  systemReplication("{'class' : 'NetworkTopologyStrategy', 'dc1' : 3 }").
  option("graph.default_property_key_cardinality").set("multiple").
  option("graph.schema_mode").set("Development").
  option("graph.allow_scan").set("true").
  option("graph.tx_groups.*.write_consistency").set("ALL").
  create()

Note the use of a wildcard * to set the write consistency for all transaction groups. If any option is modifed after graph creation, a schema.config() command must be used.

To retrieve a list of configuration options that have been set, use the describe() command:

:remote config alias g food2.g
schema.config().describe()

resulting in a list of all options that have been manually set:

==>graph.schema_mode: Development
graph.allow_scan: true
graph.tx_groups.*.write_consistency: ALL
graph.default_property_key_cardinality: Multiple

To retrieve the currently set values of schema_mode or allow_scan, set manually or by default, see the schema.getEffective* commands.

There are some configuration options for which the default (for example, values are not explicitly set) is determined by using the value of other configuration options. For instance, if allow_scan is not explicitly set, the default value is true if schema_mode is set to Development, but false if the schema_mode is set to Production. These configuration options are not linked to the default settings, leading to potentially misleading information when using schema.config().get() to discover the setting value because the default value is displayed rather than a set value.

Full graph scan settings are as follows:


setting	schema mode	scans allowed
dse.yaml schema_mode:Production	Production	no
dse.yaml schema_mode:Development	Development	yes
graph.schema_mode:Production	Production	no
graph.schema_mode:Development	Development	no
graph.allow_scan:true	Production	yes
graph.allow_scan:true	Development	yes