USER MANUALS

Configuration

The configuration of the GraphQL service is in the file <DENODO_HOME>/resources/apache-tomcat/webapps/denodo-graphql-service/WEB-INF/classes/application.properties:

In this file you can modify the following properties:

  • cors.allowed-origins: This service has Cross-origin resource sharing (CORS) enabled. The section Cross-origin Resource Sharing (CORS) (settings of published REST web services) explains what CORS is. Also, if you have installed the update 20210715 or higher, you will need to follow the steps of the section Initial Set-Up of CORS (you may have done this already if you published a Denodo REST web service with CORS enabled).

    By default, the value of the property cors.allowed-origins is *. But this value is not allowed as it is against the CORS specification because it may cause security problems.

    So you must configure the property, before using the GraphQL service, to include the list of allowed URLs (separate each URL by a comma), from which GraphQL requests are allowed. For example, http://foo.com, https://foo.bar.com.

  • context.allowed-variables: a list of context variable names permitted to pass to the X-Context-Variables header. Passing any variable not included in this list will result in a validation error and cause the query to fail. See the property syntax.

  • graphql.enable.filtering: If true, user is allowed to sort data, specify complex filters, group results and calculate aggregation functions in the GraphQL queries. If false the user is only allowed to use GraphQL standard features. Default is true.

  • graphql.enable.streaming: If true, the service will begin streaming query results to the client as soon as data is received from the Virtual DataPort server, without waiting for the entire result set to be loaded into memory. This approach helps to avoid potential memory issues when processing queries that return very large result sets. Therefore, it is highly recommended to keep this setting enabled unless you are using pagination or are confident that memory limitations will not be a concern. Default is true.

  • graphql.field-naming.camel-case-conversion: When set to true, field names in the GraphQL schema derived from VDP metadata identifiers will automatically be converted from snake-case to CamelCase notation. However, this mode is not recommended for general use, and definitively should not be enabled if the VDP server is in unrestricted mode or if metadata identifiers can contain uppercase characters, as this can result in unexpected errors and naming conflicts. Default is false.

  • graphql.max.query.complexity: GraphQL Service prevents the execution of the query if its complexity is greater than the value specified by this property. The complexity is calculated using this formula: 1 + childComplexity. Default is 200.

  • graphql.max.query.depth: GraphQL Service prevents the execution of the query if its depth is greater than the value specified by this property. Default is 5.

  • graphql.endpoint: Default is /graphql.

  • graphql.authenticated-sessions.default: GraphQL Service includes the option to maintain authenticated sessions, explained in the section Authenticated Sessions. Set to true to use this feature by default. Default is false.

  • graphql.authenticated-sessions.timeout: Specifies the time, in seconds, between client requests before the service will invalidate an authenticated session. A value of zero or less indicates that the session should never timeout. Defaults to the tomcat default timeout for sessions set in the file <DENODO_HOME>/resources/apache-tomcat/conf/web.xml.

  • query.default-page-size: Number of results returned per query. If -1 all results are retrieved. Default is 1000.

Important

By default, the service will stream data as results are received from VDP minimizing memory usage, so it is possible that in certain cases it would be preferable to disable this default limit, by setting query.default-page-size to -1.

  • vdp.datasource.driverClassName: The full package name of the Denodo driver class. Its value is com.denodo.vdp.jdbc.Driver and should not be modified.

  • vdp.datasource.jdbcUrl: URI that the GraphQL service uses to connect to Virtual DataPort. The default value is jdbc:denodo://localhost:<PORT>/?noAuth=true.

    If you change the port of Virtual DataPort (by default, 9999), modify this property accordingly.

  • vdp.admin.allowed: set to false to prevent the user account admin from accessing the GraphQL service. The service only takes this property into account when it uses HTTP Basic authentication. This property does not affect other administrator accounts, only the user account admin.

    Default value: true.

In addition to the vdp.datasource.jdbcUrl and vdp.datasource.driverClassName general datasource configuration properties, to further configure the connection pool properties (defined by the connection pool implementation) like pool size or idle connections timeout, we need to prefix them with vdp.datasource.

For example, using the default connection pool implementation (HikariCP) its particular configuration properties (detailed in the HikariCP configuration section) can be specified like:

vdp.datasource.minimumIdle=5
vdp.datasource.maximumPoolSize=20
vdp.datasource.idleTimeout=30000
vdp.datasource.maxLifetime=2000000
vdp.datasource.connectionTimeout=30000

GZIP

The GraphQL website recommends that any production GraphQL service enable GZip compression and encourage their clients to send the header Accept-Encoding: gzip.

Depending on your scenario, compressing the JSON response can increase the performance or not.

To enable GZip compression in the GraphQL Service, edit the file <DENODO_HOME>/resources/apache-tomcat/webapps/denodo-graphql-service/WEB-INF/classes/application.properties and this:

# enable response compression
server.compression.enabled=true

# comma-separated list of mime types that should be compressed
server.compression.mime-types=application/json, application/graphql

Authenticated Sessions

The GraphQL Service includes a way to leverage the performance of clients with slow authentication methods allowing them to maintain authenticated sessions.

These sessions can significantly reduce the latency of the queries made within them, but at the expense of keeping Virtual DataPort server connections open for an extended period, which could result in the exhaustion of available resources, thereby blocking new incoming client requests.

If enabled, the response to the first HTTP request of a session will include a cookie that identifies it. During subsequent requests of the same client, authentication will be performed only against the GraphQL Service instead of being delegated to the VDP server, thus improving performance.

This feature can be enabled in two different ways:

  • By default for all requests: Overwriting the configuration parameters prefixed with graphql.authenticated-sessions.* explained previously in Configuration.

  • In a per-request basis: Sending the following two optional custom HTTP headers. If sent then the default behavior set with the previous properties is overridden:

    • X-Authenticated-Session: This header overrides the default configuration property graphql.authenticated-sessions.default. It provides a way to manage the behavior of the service in a per-request basis. It accepts the values true and false.

    • X-Authenticated-Session-Timeout: This header overrides the parameter graphql.authenticated-sessions.timeout. Specifies the time, in seconds, between client requests before the service will invalidate this session. A value of zero or less indicates that the session should never timeout. Overrides the previous timeout set for a session.

Note

This feature is not recommended in most cases and is only intended for clients using time-consuming authentication methods with high performance needs, as keeping Virtual DataPort server connections open for an extended period could result in blocking new client requests due to the exhaustion of available resources.

Enable this option only when necessary and with a clear understanding of its implications to avoid performance issues.

Pass CONTEXT Clause Variables

It is possible to include variables in GraphQL queries in the same way as in the CONTEXT Clause var parameter of the VQL SELECT statement.

This variables can then be used via GETVAR inside Virtual DataPort to dynamically configure different base view and data source settings.

For security reasons, this feature is disabled by default. To enable it, you must first set the context.allowed-variables configuration property with a comma-separated list of literals (sequence of characters surrounded by single quotes) representing the names of the variables permitted in the CONTEXT clause.

Syntax of the context.allowed-variables property
context.allowed-variables=[<variable name:literal> [,  <variable name:literal>]*]

After setting this property, you can pass the desired values for the permitted variables in a GraphQL query through the X-Context-Variables HTTP header.

Syntax of the X-Context-Variables HTTP header
<variable definition> ::= <variable name:literal> = <value:literal>
X-Context-Variables: [<variable definition> [, <variable definition>]*]

Note

The <literal> token here follows the same syntax as in the VQL language meaning it is not restricted to ASCII characters like other GraphQL Names.

Tracing Requests with X-Request-ID

The GraphQL Service implements the X-Request-ID header. This allows clients to pass a random identifier through the X-Request-ID HTTP header. This identifier will be logged in the service and passed back to the client in the response, enabling direct correlation between client and server HTTP requests. By default, when provided by the client, this identifier is included in com.denodo.connect.graphql log entries, appearing at the beginning of each log message with the following format:

... - [X-Request-ID=550e8400-e29b-41d4-a716-446655440000] <Log message>

To configure the service to include the X-Request-ID in log entries from packages other than com.denodo.connect.graphql, it is necessary to modify the pattern layout of the Log4j configuration to incorporate the %X{X-Request-ID} format specifier. For instance, to prepend the X-Request-ID value in square brackets to log messages:

<PatternLayout pattern="%-4r [%t] %-5p %d{yyyy-MM-dd'T'HH:mm:ss.SSS} %c %x - %notEmpty{[X-Request-ID=%X{X-Request-ID}] }%m  %n"/>
Add feedback