DEFINE CONFIG GRAPHQL
statementThe DEFINE CONFIG GRAPHQL
statement allows you to configure how your database’s tables and functions are exposed via the GraphQL API. This configuration 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.
ImportantThe
DEFINE CONFIG GRAPHQL
statement is currently still experimental and is subject to change.
WarningBy running SurrealDB with the GraphQL module enabled, you are opting into an experimental feature. While the GraphQL module is fully functional, it is 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. It is not recommended for production use. We welcome your feedback and contributions to help improve the feature and make it more robust.
DEFINE CONFIG GRAPHQL
statement.DEFINE CONFIG GRAPHQL
statement.SURREAL_EXPERIMENTAL_GRAPHQL
environment variable set to true
.
SurrealQL SyntaxDEFINE CONFIG [OVERWRITE | IF NOT EXISTS] GRAPHQL [ AUTO | NONE] [ TABLES (AUTO | NONE | INCLUDE table1, table2, ...) ] [ FUNCTIONS (AUTO | NONE | INCLUDE [function1, function2, ...] | EXCLUDE [function1, function2, ...]) ]
DEFINE CONFIG GRAPHQL
statement must be executed before any GraphQL queries can be made.NotConfigured
error.-- Define GraphQL configuration DEFINE CONFIG GRAPHQL AUTO;
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;
NoteThe
EXCLUDE
option forTABLES
is currently not implemented.
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];
IF NOT EXISTS
clauseThe 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;
OVERWRITE
clauseThe 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;
This example defines a GraphQL configuration that includes specific tables and functions.
DEFINE CONFIG GRAPHQL TABLES INCLUDE user, post FUNCTIONS INCLUDE [getUser, listPosts];
This example defines a GraphQL configuration that automatically includes all tables and functions.
DEFINE CONFIG GRAPHQL TABLES AUTO FUNCTIONS AUTO;
This example defines a GraphQL configuration that includes all functions except specific ones.
DEFINE CONFIG GRAPHQL FUNCTIONS EXCLUDE [debugFunction, testFunction];
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;
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;
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.
-- 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.
-- 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 } ] } }
-- 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.
You can use limit
, start
, order
, and filter
in your GraphQL queries to control the data returned.
query { foo(limit: 1) { id val } }
query { foo(start: 1) { id val } }
query { foo(order: { desc: val }) { id val } }
query { foo(filter: { val: { eq: 42 } }) { id val } }
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.
ImportantAlways ensure you have the necessary permissions and have selected the appropriate namespace and database before using the
DEFINE CONFIG GRAPHQL
statement.
DEFINE CONFIG GRAPHQL
to enable and configure the GraphQL API.OVERWRITE
and IF NOT EXISTS
clauses as needed to manage your configuration.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.