Reference configuration

The following is a copy of the dse-reference.conf file matching the version of this documentation. It is packaged in the dse-java-driver-core JAR artifact, and used at runtime to provide the default values for all configuration options (in the sources, it can be found under core/src/main/resources).

Note that this file also inherits all the contents of the OSS driver reference file.

See the configuration page for more explanations.

# Reference configuration for the DataStax Enterprise Java driver.
#
# This configuration inherits from the open-source Apache Cassandra® driver configuration. In other
# words, any option not explicitly defined below gets its value from the `reference.conf` file
# shipped with the java-driver-core.jar that this DSE driver depends on.
#
# You can place your own `application.conf` file in the classpath to override any option.
#
# Note that the configuration loading mechanism is pluggable (see
# DseSessionBuilder.withConfigLoader).
#
# This file is in HOCON format, see https://github.com/typesafehub/config/blob/master/HOCON.md.
datastax-java-driver {

  basic {
    # The name of the application using the session.
    #
    # It will be sent in the STARTUP protocol message for each new connection established by the
    # driver, and may be used by future DSE versions for monitoring purposes.
    #
    # This can also be defined programmatically with DseSessionBuilder.withApplicationName(). If you
    # specify both, the programmatic value takes precedence and this option is ignored.
    #
    # Required: no
    # Modifiable at runtime: no
    # Overridable in a profile: no
    // application.name =

    # The version of the application using the session.
    #
    # It will be sent in the STARTUP protocol message for each new connection established by the
    # driver, and may be used by future DSE versions for monitoring purposes.
    #
    # This can also be defined programmatically with DseSessionBuilder.withApplicationVersion(). If
    # you specify both, the programmatic value takes precedence and this option is ignored.
    #
    # Required: no
    # Modifiable at runtime: no
    # Overridable in a profile: no
    // application.version =

    load-balancing-policy {
      # The DSE driver ships with a specific load balancing policy implementation that is capable,
      # among other things, of avoiding slow nodes and handling analytics queries:
      # DseLoadBalancingPolicy.
      #
      # You can also specify any other custom implementation class, provided that it implements
      # LoadBalancingPolicy and has a public constructor with two arguments: the DriverContext and a
      # String representing the profile name.
      class = DseLoadBalancingPolicy

    }
  }

  basic.graph {
    # The name of the graph targeted by graph statements.
    #
    # This can also be overridden programmatically with GraphStatement.setGraphName(). If both are
    # specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no. In particular, system queries -- such as creating or dropping a graph -- must be
    #   executed without a graph name (see also basic.graph.is-system-query).
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // name = your-graph-name

    # The traversal source to use for graph statements.
    #
    # This setting doesn't usually need to change, unless executing OLAP queries, which require the
    # traversal source "a".
    #
    # This can also be overridden programmatically with GraphStatement.setTraversalSource(). If both
    # are specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    traversal-source = "g"

    # Whether a script statement represents a system query.
    #
    # Script statements that access the `system` variable *must not* specify a graph name (otherwise
    # `system` is not available). However, if your application executes a lot of non-system
    # statements, it is convenient to configure basic.graph.name to avoid repeating it every time.
    # This option allows you to ignore that global graph name, for example in a specific profile.
    #
    # This can also be overridden programmatically with ScriptGraphStatement.setSystemQuery(). If
    # both are specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no (defaults to false)
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // is-system-query = false

    # The read consistency level to use for graph statements.
    #
    # DSE Graph is able to distinguish between read and write timeouts for the internal storage
    # queries that will be produced by a traversal. Hence the consistency level for reads and writes
    # can be set separately.
    #
    # This can also be overridden programmatically with GraphStatement.setReadConsistencyLevel(). If
    # both are specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no (defaults to request.basic.consistency)
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // read-consistency = LOCAL_QUORUM

    # The write consistency level to use for graph queries.
    #
    # DSE Graph is able to distinguish between read and write timeouts for the internal storage
    # queries that will be produced by a traversal. Hence the consistency level for reads and writes
    # can be set separately.
    #
    # This can also be overridden programmatically with GraphStatement.setReadConsistencyLevel(). If
    # both are specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no (defaults to request.basic.consistency)
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // write-consistency = LOCAL_ONE

    # How long the driver waits for a graph request to complete. This is a global limit on the
    # duration of a session.execute() call, including any internal retries the driver might do.
    #
    # Graph statements behave a bit differently than regular CQL requests (hence this dedicated
    # option instead of reusing basic.request.timeout): by default, the client timeout is not set,
    # and the driver will just wait as long as needed until the server replies (which is itself
    # governed by server-side timeout configuration).
    # If you specify a client timeout with this option, then the driver will fail the request after
    # the given time; note that the value is also sent along with the request, so that the server
    # can also time out early and avoid wasting resources on a response that the client has already
    # given up on.
    #
    # This can also be overridden programmatically with GraphStatement.setTimeout(). If both are
    # specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no (defaults to request.basic.consistency)
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // timeout = 10 seconds
  }

  # The component that handles authentication on each new connection.
  #
  # Required: no. If the 'class' child option is absent, no authentication will occur.
  # Modifiable at runtime: no
  # Overridable in a profile: no
  advanced.auth-provider {
    # The class of the provider. If it is not qualified, the driver assumes that it resides in one
    # of the following packages:
    # - com.datastax.oss.driver.internal.core.auth
    # - com.datastax.dse.driver.internal.core.auth
    #
    # The DSE driver provides 3 implementations out of the box:
    # - PlainTextAuthProvider: uses plain-text credentials. It requires the `username` and
    #   `password` options below. Should be used only when authenticating against Apache
    #   Cassandra(R) clusters; not recommended when authenticating against DSE clusters.
    # - DsePlainTextAuthProvider: provides SASL authentication using the PLAIN mechanism for DSE
    #   clusters secured with DseAuthenticator. It requires the `username` and `password` options
    #   below, and optionally, an `authorization-id`.
    # - DseGssApiAuthProvider: provides GSSAPI authentication for DSE clusters secured with
    #   DseAuthenticator. Read the javadocs of this authenticator for detailed instructions.
    #
    # You can also specify a custom class that implements AuthProvider and has a public constructor
    # with a DriverContext argument (to simplify this, the driver provides two abstract classes that
    # can be extended: DsePlainTextAuthProviderBase and DseGssApiAuthProviderBase).
    #
    # Finally, you can configure a provider instance programmatically with
    # DseSessionBuilder#withAuthProvider. In that case, it will take precedence over the
    # configuration.
    // class = DsePlainTextAuthProvider
    #
    # Sample configuration for plain-text authentication providers:
    // username = cassandra
    // password = cassandra
    #
    # Proxy authentication: allows to login as another user or role (valid for both
    # DsePlainTextAuthProvider and DseGssApiAuthProvider):
    // authorization-id = userOrRole
    #
    # The settings below are only applicable to DseGssApiAuthProvider:
    #
    # Service name. For example, if in your dse.yaml configuration file the
    # "kerberos_options/service_principal" setting is "cassandra/my.host.com@MY.REALM.COM", then set
    # this option to "cassandra":
    //service = "cassandra"
    #
    # Login configuration. It is also possible to provide login configuration through a standard
    # JAAS configuration file. The below configuration is just an example, see all possible options
    # here:
    # https://docs.oracle.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html
    // login-configuration {
    //   principal = "cassandra@DATASTAX.COM"
    //   useKeyTab = "true"
    //   refreshKrb5Config = "true"
    //   keyTab = "/path/to/keytab/file"
    // }
    #
    # Internal SASL properties, if any, such as QOP.
    // sasl-properties {
    //   javax.security.sasl.qop = "auth-conf"
    // }
  }

  advanced.graph {
    # The sub-protocol the driver will use to communicate with DSE Graph, on top of the Cassandra
    # native protocol.
    #
    # You should almost never have to change this: the driver sets it automatically, based on the
    # information it has about the server. One exception is if you use the script API against a
    # legacy DSE version (5.0.3 or older). In that case, you need to force the sub-protocol to
    # "graphson-1.0".
    #
    # This can also be overridden programmatically with GraphStatement.setSubProtocol(). If both are
    # specified, the programmatic value takes precedence, and this option is ignored.
    #
    # Required: no
    # Modifiable at runtime: yes, the new value will be used for requests issued after the change.
    # Overridable in a profile: yes
    // sub-protocol = "graphson-2.0"
  }

  advanced.metrics {

    # The session-level metrics (all disabled by default).
    #
    # This section only lists metrics specific to the DSE driver. Please refer to the OSS driver's
    # reference.conf file to know which metrics are made available by the OSS driver.
    #
    # Required: yes
    # Modifiable at runtime: no
    # Overridable in a profile: no
    session {
      enabled = [

        # The throughput and latency percentiles of continuous CQL requests (exposed as a Timer).
        #
        # This metric is a session-level metric and corresponds to the overall duration of the
        # session.executeContinuously() call, including any retry.
        #
        # Note that this metric is analogous to the OSS driver's 'cql-requests' metrics, but for
        # continuous paging requests only. Continuous paging requests do not update the
        # 'cql-requests' metric, because they are usually much longer. Only the following metrics
        # are updated during a continuous paging request:
        #
        # - At node level: all the usual metrics available for normal CQL requests, such as
        #   'cql-messages' and error-related metrics;
        # - At session level: only 'continuous-cql-requests' is updated (this metric).
        // continuous-cql-requests,

      ]

      # Extra configuration (for the metrics that need it)

      # Required: if the 'continuous-cql-requests' metric is enabled
      # Modifiable at runtime: no
      # Overridable in a profile: no
      continuous-cql-requests {

        # The largest latency that we expect to record for a continuous paging request.
        #
        # This is used to scale internal data structures. If a higher recording is encountered at
        # runtime, it is discarded and a warning is logged.
        highest-latency = 120 seconds

        # The number of significant decimal digits to which internal structures will maintain
        # value resolution and separation (for example, 3 means that recordings up to 1 second
        # will be recorded with a resolution of 1 millisecond or better).
        #
        # This must be between 0 and 5. If the value is out of range, it defaults to 3 and a
        # warning is logged.
        significant-digits = 3

        # The interval at which percentile data is refreshed.
        #
        # The driver records latency data in a "live" histogram, and serves results from a cached
        # snapshot. Each time the snapshot gets older than the interval, the two are switched.
        # Note that this switch happens upon fetching the metrics, so if you never fetch the
        # recording interval might grow higher (that shouldn't be an issue in a production
        # environment because you would typically have a metrics reporter that exports to a
        # monitoring tool at a regular interval).
        #
        # In practice, this means that if you set this to 5 minutes, you're looking at data from a
        # 5-minute interval in the past, that is at most 5 minutes old. If you fetch the metrics
        # at a faster pace, you will observe the same data for 5 minutes until the interval
        # expires.
        #
        # Note that this does not apply to the total count and rates (those are updated in real
        # time).
        refresh-interval = 5 minutes
      }
    }

    # The node-level metrics (all disabled by default).
    #
    # This section only lists metrics specific to the DSE driver. Please refer to the OSS driver's
    # reference.conf file to knwow which metrics are made available by the OSS driver.
    #
    # Required: yes
    # Modifiable at runtime: no
    # Overridable in a profile: no
    node {
      enabled = [

      ]
    }
  }

  # Options to control the execution of continuous paging requests.
  advanced.continuous-paging {

    # The page size.
    #
    # The value specified here can be interpreted in number of rows
    # or in number of bytes, depending on the unit defined with page-unit (see below).
    #
    # It controls how many rows (or how much data) will be retrieved simultaneously in a single
    # network roundtrip (the goal being to avoid loading too many results in memory at the same
    # time). If there are more results, additional requests will be used to retrieve them (either
    # automatically if you iterate with the sync API, or explicitly with the async API's
    # fetchNextPage method).
    #
    # The default is the same as the driver's normal request page size,
    # i.e., 5000 (rows).
    #
    # Required: yes
    # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
    #   the change
    # Overridable in a profile: yes
    page-size = ${datastax-java-driver.basic.request.page-size}

    # Whether the page-size option should be intepreted in number of rows or bytes.
    #
    # The default is false, i.e., the page size will be interpreted in number of rows.
    #
    # Required: yes
    # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
    #   the change
    # Overridable in a profile: yes
    page-size-in-bytes = false

    # The maximum number of pages to return.
    #
    # The default is zero, which means retrieve all pages.
    #
    # Required: yes
    # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
    #   the change
    # Overridable in a profile: yes
    max-pages = 0

    # Returns the maximum number of pages per second.
    #
    # The default is zero, which means no limit.
    #
    # Required: yes
    # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
    #   the change
    # Overridable in a profile: yes
    max-pages-per-second = 0

    # The maximum number of pages that can be stored in the local queue.
    #
    # This value must be positive. The default is 4.
    #
    # Required: yes
    # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
    #   the change
    # Overridable in a profile: yes
    max-enqueued-pages = 4

    # Timeouts for continuous paging.
    #
    # Note that there is no global timeout for continuous paging as there is
    # for regular queries, because continuous paging queries can take an arbitrarily
    # long time to complete.
    #
    # Instead, timeouts are applied to each exchange between the driver and the coordinator. In
    # other words, if the driver decides to retry, all timeouts are reset.
    timeout {

      # How long to wait for the coordinator to send the first page.
      #
      # Required: yes
      # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
      #   the change
      # Overridable in a profile: yes
      first-page = 2 seconds

      # How long to wait for the coordinator to send subsequent pages.
      #
      # Required: yes
      # Modifiable at runtime: yes, the new value will be used for continuous requests issued after
      #   the change
      # Overridable in a profile: yes
      other-pages = 1 second

    }
  }

  # Options to control monitor reporting integration
  advanced.monitor-reporting {
    # Whether the send of events to monitor reporting system should be enabled.
    #
    # The default is true, which means send events to monitor reporting system
    #
    # Required: no (defaults to true)
    # Modifiable at runtime: no
    # Overridable in a profile: no
    enabled = true
  }

  profiles {
    # An example configuration profile for graph requests.
    //    my-graph-profile-example {
    //      graph {
    //        read-consistency-level = LOCAL_QUORUM
    //        write-consistency-level = LOCAL_ONE
    //      }
    //    }

    # An example pre-defined configuration profile for OLAP graph queries.
    //    graph-olap {
    //      graph {
    //        traversal-source = "a" // traversal source needs to be set to "a" for OLAP queries.
    //      }
    //    }
  }
}