DEFINE CONFIG statement

The DEFINE CONFIG statement allows you to set external configurations on your database. It can be used to configure API middleware and permissions, or to configure how the database’s tables and functions are exposed via the GraphQL API.

Warning

By running SurrealDB with configurations for the database API or the GraphQL module, you are opting into an experimental feature. While these features are fully functional, they are still considered experimental and may not be as stable as the core SurrealQL module which means we cannot guarantee that it will provide the same security guarantees. They are not recommended for production use. We welcome your feedback and contributions to help improve the feature and make it more robust.

Requirements

• You must be authenticated as a root, namespace, or database user before you can use the DEFINE CONFIG GRAPHQL statement.
• You must select your namespace and database before you can use the DEFINE CONFIG GRAPHQL statement.
• You must define at least one table in your database for the GraphQL API to function.
• You must have started the SurrealDB instance with the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable set to "graphql".

Statement syntax

SurrealQL Syntax
DEFINE CONFIG [ OVERWRITE | IF NOT EXISTS ] 

  [ API [ MIDDLEWARE @expression, .. ] [ PERMISSIONS [ NONE | FULL | @expression ] ]

  [ GRAPHQL 
    [ AUTO | NONE ]
    [ TABLES (AUTO | NONE | INCLUDE table1, table2, ...) ]
    [ FUNCTIONS (AUTO | NONE | INCLUDE [function1, function2, ...] | EXCLUDE [function1, function2, ...]) ] ]

DEFINE CONFIG API

The DEFINE CONFIG API statement can be used to set middleware and permissions in order to alter the behaviour of the database for guest and record users. This middleware can be used in cases such as rate limiting on the query language and setting how many resources a client can read or alter at a time.

DEFINE CONFIG API is often used in conjunction with a flag or environment variable to disable arbitrary queries, thereby forcing record and anonymous users to interact with the database via API endpoints alone.

The following is an example of a DEFINE CONFIG statement that includes a timeout and a single header in the responses of all API endpoints.

DEFINE CONFIG API
    MIDDLEWARE 
        api::timeout(10s),
        api::res::headers({
            'Access-Control-Allow-Origin': '*'
        });

To set the actual API endpoints and their middleware, a DEFINE API statement is used for each endpoint.

The behaviour of API endpoints can be tested using the api::invoke method, or through a regular HTTP call to the endpoint that includes the namespace and database name.

This next example uses DEFINE CONFIG to set a single response header, followed by two endpoints that return different output.

DEFINE CONFIG API
    MIDDLEWARE 
        api::res::headers({
            'Access-Control-Allow-Origin': '*'
        });

DEFINE API "/test" FOR get THEN {};
DEFINE API "/test2" FOR get THEN {
    RETURN {
        body: {
            some: "data"
        }
    }
};

api::invoke("/test");
api::invoke("/test2");

The query shows that the endpoints return a combination of the DEFINE CONFIG middleware and the response object set in the DEFINE API statements.

-------- Query --------

{
	headers: {
		"access-control-allow-origin": '*'
	},
	raw: false,
	status: 200
}

-------- Query --------

{
	body: {
		some: 'data'
	},
	headers: {
		"access-control-allow-origin": '*'
	},
	raw: false,
	status: 200
}

Note that the middleware and permissions inside individual DEFINE API statements will override the middleware in a DEFINE CONFIG API statement. In the following example, the default 10s timeout is set to a single microsecond for the "/test" endpoint, giving the intended query no time to complete.

DEFINE CONFIG API
    MIDDLEWARE 
        api::timeout(10s),
        api::res::headers({
            'Access-Control-Allow-Origin': '*'
        });

DEFINE API OVERWRITE "/test"
    FOR get 
        MIDDLEWARE
            api::timeout(1µs)
        THEN {
            RETURN {
                status: 200,
                body: { 
                    data: (SELECT * FROM person),
                    however: "This will probably never return because the timeout is 1 microsecond"
                }
            };
        };

api::invoke("/test");

Output
'The query was not executed because it exceeded the timeout'

DEFINE CONFIG GRAPHQL

The configuration set using the DEFINE CONFIG GRAPHQL is essential for enabling GraphQL functionality in your database, specifying which tables and functions should be included or excluded from the GraphQL schema.

The GraphQL configuration defined using this statement dictates how clients interact with your database through GraphQL queries and mutations.

Important Notes

• The DEFINE CONFIG GRAPHQL statement must be executed before any GraphQL queries can be made.
• If you attempt to use the GraphQL API without defining the configuration, you will receive a NotConfigured error.
• If no tables are defined in the database, you will receive an error stating “No tables found in database” when attempting to use the GraphQL API.

Example usage

-- Define GraphQL configuration
DEFINE CONFIG GRAPHQL  AUTO;

Tables Configuration

The TABLES clause in the DEFINE CONFIG GRAPHQL statement specifies how tables are exposed via GraphQL. There are four options for the TABLES configuration:

• AUTO: Automatically include all tables in the GraphQL schema.
• NONE: Do not include any tables in the GraphQL schema.
• INCLUDE: Specify a list of tables to include in the GraphQL schema.
• EXCLUDE: Specify a list of tables to exclude from the GraphQL schema.

AUTO

When you specify TABLES AUTO, all tables in the database are automatically included in the GraphQL schema.

DEFINE CONFIG GRAPHQL TABLES AUTO;

NONE

When you specify TABLES NONE, no tables are included in the GraphQL schema.

DEFINE CONFIG GRAPHQL TABLES NONE;

INCLUDE

You can specify a list of tables to include in the GraphQL schema using the INCLUDE clause. The list of tables is specified as a comma-separated list without brackets.

DEFINE CONFIG GRAPHQL TABLES INCLUDE user, post, comment;

Note

The EXCLUDE option for TABLES is currently not implemented.

Functions Configuration

The FUNCTIONS clause in the DEFINE CONFIG GRAPHQL statement specifies how functions are exposed via GraphQL. There are four options for the FUNCTIONS configuration:

• AUTO: Automatically include all functions in the GraphQL schema.
• NONE: Do not include any functions in the GraphQL schema.
• INCLUDE: Specify a list of functions to include in the GraphQL schema.
• EXCLUDE: Specify a list of functions to exclude from the GraphQL schema.

AUTO

When you specify FUNCTIONS AUTO, all functions in the database are automatically included in the GraphQL schema.

DEFINE CONFIG GRAPHQL FUNCTIONS AUTO;

NONE

When you specify FUNCTIONS NONE, no functions are included in the GraphQL schema.

DEFINE CONFIG GRAPHQL FUNCTIONS NONE;

INCLUDE

You can specify a list of functions to include in the GraphQL schema using the INCLUDE clause. The list of functions is specified as a comma-separated list enclosed in square brackets [].

DEFINE CONFIG GRAPHQL FUNCTIONS INCLUDE [getUser, listPosts, searchComments];

EXCLUDE

You can specify a list of functions to exclude from the GraphQL schema using the EXCLUDE clause. The list of functions is specified as a comma-separated list enclosed in square brackets [].

DEFINE CONFIG GRAPHQL FUNCTIONS EXCLUDE [debugFunction, testFunction];

Using IF NOT EXISTS clause

The IF NOT EXISTS clause can be used to define the GraphQL configuration only if it does not already exist. This is useful when you want to ensure that the configuration is only created if it does not already exist, preventing errors due to duplicate definitions.

-- Define GraphQL configuration only if it does not already exist
DEFINE CONFIG GRAPHQL IF NOT EXISTS TABLES AUTO FUNCTIONS AUTO;

Using OVERWRITE clause

The OVERWRITE clause can be used to redefine the GraphQL configuration, overwriting any existing configuration. This is useful when you want to update or modify the existing GraphQL configuration.

-- Redefine GraphQL configuration, overwriting existing configuration
DEFINE CONFIG OVERWRITE GRAPHQL TABLES INCLUDE user, post FUNCTIONS NONE;

Examples

Example 1: Include specific tables and functions

This example defines a GraphQL configuration that includes specific tables and functions.

DEFINE CONFIG GRAPHQL TABLES INCLUDE user, post FUNCTIONS INCLUDE [getUser, listPosts];

Example 2: Automatically include all tables and functions

This example defines a GraphQL configuration that automatically includes all tables and functions.

DEFINE CONFIG GRAPHQL TABLES AUTO FUNCTIONS AUTO;

Example 3: Exclude specific functions

This example defines a GraphQL configuration that includes all functions except specific ones.

DEFINE CONFIG GRAPHQL FUNCTIONS EXCLUDE [debugFunction, testFunction];

Error Handling

NotConfigured Error

If you attempt to access the GraphQL endpoint without defining the GraphQL configuration, you will receive a NotConfigured error.

Error Response
{
  "error": "NotConfigured: GraphQL endpoint is not configured. Please define the GraphQL configuration using DEFINE CONFIG GRAPHQL."
}

Execute the DEFINE CONFIG GRAPHQL statement to define the GraphQL configuration.

-- Define GraphQL configuration
DEFINE CONFIG GRAPHQL TABLES AUTO FUNCTIONS AUTO;

No Tables Found Error

If you have defined the GraphQL configuration but no tables are defined in the database, you will receive an error stating “No tables found in database” when attempting to use the GraphQL API. You can fix this by defining at least one table in your database using the DEFINE TABLE statement.

Error Response
{
  "error": "No tables found in database. Please define at least one table to use the GraphQL API."
}

Solution: Define at least one table in your database.

DEFINE TABLE foo SCHEMAFUL;
DEFINE FIELD val ON foo TYPE int;
CREATE foo:1 SET val = 42;

Authentication Errors When Accessing Data via GraphQL

Cause: Insufficient permissions or incorrect authentication credentials.

Solution: Ensure you are authenticated as a user with the necessary permissions and that the permissions on tables and fields are correctly configured.

Authentication and Permissions

• The GraphQL API respects SurrealDB’s authentication and permission model.
• You must authenticate using the appropriate credentials to access data via GraphQL.
• Permissions set on tables and fields will affect the data accessible through the GraphQL API.
• If you attempt to access data without sufficient permissions, you will receive an authentication error.

Example: Basic Authentication

-- Define a user with access permissions
DEFINE USER my_user ON DATABASE PASSWORD 'my_password';
DEFINE ACCESS user ON DATABASE TYPE RECORD
  SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
  SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
  DURATION FOR SESSION 60s, FOR TOKEN 1d;

-- Define a table with permissions
DEFINE TABLE foo SCHEMAFUL PERMISSIONS FOR select WHERE $auth.email = email;
DEFINE FIELD email ON foo TYPE string;
DEFINE FIELD val ON foo TYPE int;

-- Insert data
CREATE foo:1 SET val = 42, email = "user@example.com";
CREATE foo:2 SET val = 43, email = "other@example.com";

When querying the GraphQL API as user@example.com, only the records where email = "user@example.com" will be accessible due to the permissions set.

Examples

Example 1: Defining GraphQL Configuration and Fetching Data

-- Define GraphQL configuration to include all tables automatically
DEFINE CONFIG GRAPHQL TABLES AUTO;

-- Define a table and insert data
DEFINE TABLE foo SCHEMAFUL;
DEFINE FIELD val ON foo TYPE int;
CREATE foo:1 SET val = 42;
CREATE foo:2 SET val = 43;

Now, you can fetch data via GraphQL:

query {
  foo {
    id
    val
  }
}

Response:

{
  "data": {
    "foo": [
      {
        "id": "foo:1",
        "val": 42
      },
      {
        "id": "foo:2",
        "val": 43
      }
    ]
  }
}

Example 2: Including Specific Tables

-- Define GraphQL configuration to include only specific tables
DEFINE CONFIG OVERWRITE GRAPHQL TABLES INCLUDE foo;

When querying the GraphQL schema, only the included tables will be available.

Example 3: Using Limit, Start, Order, and Filter in GraphQL Queries

You can use limit, start, order, and filter in your GraphQL queries to control the data returned.

Limit

query {
  foo(limit: 1) {
    id
    val
  }
}

Start

query {
  foo(start: 1) {
    id
    val
  }
}

Order

query {
  foo(order: { desc: val }) {
    id
    val
  }
}

Filter

query {
  foo(filter: { val: { eq: 42 } }) {
    id
    val
  }
}

More Information

The DEFINE CONFIG GRAPHQL statement is essential for enabling and configuring the GraphQL API in SurrealDB. By specifying which tables and functions are included or excluded, you can fine-tune the GraphQL schema to match your application’s needs.

• Authentication: Ensure you are authenticated with the appropriate credentials.
• Permissions: Set up permissions on tables and fields to control access via GraphQL.
• Configuration: The GraphQL configuration must be defined before using the GraphQL API.
• Error Handling: Be aware of possible errors when the configuration is missing or incomplete.

Important

Always ensure you have the necessary permissions and have selected the appropriate namespace and database before using the DEFINE CONFIG GRAPHQL statement.

Summary

• Use DEFINE CONFIG GRAPHQL to enable and configure the GraphQL API.
• Define your tables and set up permissions to control data access.
• Use the OVERWRITE and IF NOT EXISTS clauses as needed to manage your configuration.
• Always authenticate with appropriate credentials when accessing the GraphQL API.
• Utilize GraphQL query features like limit, start, order, and filter to control the data returned.

By following these guidelines, you can effectively use the DEFINE CONFIG GRAPHQL statement to configure and interact with your SurrealDB database via GraphQL.