Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/content/reference/query-language/clauses/__category.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"position": 3,
"title": "Clauses"
"position": 4,
"title": "Clauses"
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"position": 4,
"title": "Functions"
"position": 5,
"title": "Functions"
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"position": 5,
"title": "Scripting"
"position": 6,
"title": "Scripting"
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"position": 2,
"title": "Statements"
"position": 3,
"title": "Statements"
}

This file was deleted.

This file was deleted.

17 changes: 7 additions & 10 deletions src/content/reference/query-language/statements/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,21 @@ SurrealDB provides statements to configure resources, control execution flow, an

SurrealDB has a large variety of statements. They can be divided into three types:

* Statements that define and access database resources,
* Statements that interact with database resources,
* Statements used for control flow and handling manual transactions,
* Statements used in the context of queries, usually in CRUD (create, read, update, delete) operations.

> [!NOTE]
> Statements for **defining, altering, and removing** database resources (such as `DEFINE`, `ALTER`, and `REMOVE`) are covered in the [Structure](/docs/reference/query-language/structure/overview) section.

### Database resource statements

These statements pertain to defining, removing, altering, and rebuilding database resources. They are:
These statements interact with existing database resources. They are:

* [`DEFINE`](/docs/reference/query-language/statements/define/overview) statements to define database resources,
* [`ALTER`](/docs/reference/query-language/statements/alter) statements to alter certain resources,
* [`REMOVE`](/docs/reference/query-language/statements/remove) statements to remove resources,
* [`ACCESS`](/docs/reference/query-language/statements/access) to manage access grants,
* [`REBUILD`](/docs/reference/query-language/statements/rebuild) to rebuild an index,
* [`ACCESS`](/docs/reference/query-language/statements/access) to manage access grants.

Some other statements pertain to using defined resources. They are:

* [`USE`](/docs/reference/query-language/statements/use) to move from one namespace or database to another,
* [`INFO`](/docs/reference/query-language/statements/info) statements to see the definitions for resources,
* [`INFO`](/docs/reference/query-language/statements/info) to see the definitions for resources,
* [`SHOW`](/docs/reference/query-language/statements/show) to see the changefeed for a table or database.

### Control flow statements
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"position": 2,
"title": "Structure"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"position": 2,
"title": "ALTER"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"position": 3,
"title": "DEFINE"
}
53 changes: 53 additions & 0 deletions src/content/reference/query-language/structure/overview.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
position: 1
title: Structure
description: "Reference overview: SurrealQL statements for defining, altering, and removing database resources such as namespaces, databases, tables, fields, indexes, events, and access methods."
---

# Structure

SurrealDB provides statements to define and manage the schema and resources of a database. These statements control what exists in the database rather than what data is stored in it.

## Types of structure statements

Structure statements fall into three categories:

* [`DEFINE`](/docs/reference/query-language/structure/define/overview) — declare and configure database resources,
* [`ALTER`](/docs/reference/query-language/structure/alter/overview) — modify previously defined resources,
* [`REMOVE`](/docs/reference/query-language/structure/remove) — remove resources from the database.

### DEFINE

The `DEFINE` statement is used to declare schema elements and configure how SurrealDB behaves. Resources that can be defined include:

* [`NAMESPACE`](/docs/reference/query-language/structure/define/namespace) — top-level namespace,
* [`DATABASE`](/docs/reference/query-language/structure/define/database) — database within a namespace,
* [`USER`](/docs/reference/query-language/structure/define/user) — user account at root, namespace, or database level,
* [`ACCESS`](/docs/reference/query-language/structure/define/access/index) — authentication access methods (JWT, bearer token, or record-based),
* [`TABLE`](/docs/reference/query-language/structure/define/table) — table with optional schema, permissions, and projections,
* [`FIELD`](/docs/reference/query-language/structure/define/field) — field on a table with type, default, assertions, and permissions,
* [`INDEX`](/docs/reference/query-language/structure/define/indexes) — index on a table for fast lookups and full-text search,
* [`EVENT`](/docs/reference/query-language/structure/define/event) — event triggered on table mutations,
* [`FUNCTION`](/docs/reference/query-language/structure/define/function) — custom reusable SurrealQL function,
* [`PARAM`](/docs/reference/query-language/structure/define/param) — global parameter available across queries,
* [`ANALYZER`](/docs/reference/query-language/structure/define/analyzer) — full-text search analyzer,
* [`API`](/docs/reference/query-language/structure/define/api) — HTTP API endpoint,
* [`BUCKET`](/docs/reference/query-language/structure/define/bucket) — file storage bucket,
* [`CONFIG`](/docs/reference/query-language/structure/define/config) — database-level configuration,
* [`MODULE`](/docs/reference/query-language/structure/define/module) — JavaScript module,
* [`SEQUENCE`](/docs/reference/query-language/structure/define/sequence) — auto-incrementing sequence.

### ALTER

The `ALTER` statement modifies the behaviour of existing resources. It can be used to:

* Modify previously defined tables and fields (for other resources, use the `OVERWRITE` clause in `DEFINE`),
* Use clauses not available in `DEFINE`, such as `PREPARE REMOVE` to stage an index for removal, `COMPACT` to compact storage, or `QUERY_TIMEOUT` to set a datastore-level timeout.

See the [`ALTER` overview](/docs/reference/query-language/structure/alter/overview) for full details.

### REMOVE

The `REMOVE` statement removes a resource from the database. It is analogous to `DROP` in SQL. Resources that can be removed include namespaces, databases, users, access methods, tables, fields, indexes, events, functions, parameters, analyzers, APIs, buckets, config entries, modules, and sequences.

See the [`REMOVE` reference](/docs/reference/query-language/structure/remove) for full details.
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
position: 20
position: 4
title: REMOVE
description: "The REMOVE statement is used to remove resources such as databases, tables, indexes, events and more."
---
Expand All @@ -16,69 +16,32 @@ Similar to an SQL DROP statement.

```syntax title="SurrealQL Syntax"
REMOVE [
ACCESS [ IF EXISTS ] @name ON [ NAMESPACE | DATABASE ]
| ANALYZER [ IF EXISTS ] @name
| API [ IF EXISTS ] @name
| CONFIG [ IF EXISTS ] [ GRAPHQL | API | DEFAULT ]
| DATABASE [ IF EXISTS ] @name
| EVENT [ IF EXISTS ] @name ON [ TABLE ] @table
| FIELD [ IF EXISTS ] @name ON [ TABLE ] @table
| FUNCTION [ IF EXISTS ] @name
| INDEX [ IF EXISTS ] @name ON [ TABLE ] @table
| NAMESPACE [ IF EXISTS ] @name
| PARAM [ IF EXISTS ] @name
| TABLE [ IF EXISTS ] @name
| USER [ IF EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ]
ACCESS [ IF EXISTS ] @name ON [ NAMESPACE | DATABASE ]
| ANALYZER [ IF EXISTS ] @name
| API [ IF EXISTS ] @name
| CONFIG [ IF EXISTS ] [ GRAPHQL | API | DEFAULT ]
| DATABASE [ IF EXISTS ] @name
| EVENT [ IF EXISTS ] @name ON [ TABLE ] @table
| FIELD [ IF EXISTS ] @name ON [ TABLE ] @table
| FUNCTION [ IF EXISTS ] @name
| INDEX [ IF EXISTS ] @name ON [ TABLE ] @table
| NAMESPACE [ IF EXISTS ] @name
| PARAM [ IF EXISTS ] @name
| TABLE [ IF EXISTS ] @name
| USER [ IF EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ]
]
```

</TabItem>
<TabItem label="Railroad Diagram">

export const removeAst = {
type: "Diagram",
padding: [10, 20, 10, 20],
children: [
{ type: "Sequence", children: [
{ type: "Terminal", text: "REMOVE" },
{ type: "Choice", index: 1, children: [

{ type: "Sequence", children: [ { type: "Terminal", text: "ACCESS" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" }, { type: "Terminal", text: "ON" }, { type: "Choice", index: 1, children: [ { type: "Terminal", text: "NAMESPACE" }, { type: "Terminal", text: "DATABASE" } ] } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "ANALYZER" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "API" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "CONFIG" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "Choice", index: 1, children: [ { type: "Terminal", text: "GRAPHQL" }, { type: "Terminal", text: "API" }, { type: "Terminal", text: "DEFAULT" } ] } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "DATABASE" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "EVENT" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" }, { type: "Terminal", text: "ON" }, { type: "Optional", child: { type: "Terminal", text: "TABLE" } }, { type: "NonTerminal", text: "@table" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "FIELD" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" }, { type: "Terminal", text: "ON" }, { type: "Optional", child: { type: "Terminal", text: "TABLE" } }, { type: "NonTerminal", text: "@table" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "FUNCTION" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "INDEX" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" }, { type: "Terminal", text: "ON" }, { type: "Optional", child: { type: "Terminal", text: "TABLE" } }, { type: "NonTerminal", text: "@table" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "NAMESPACE" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "PARAM" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "Terminal", text: "$" }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "TABLE" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" } ] },

{ type: "Sequence", children: [ { type: "Terminal", text: "USER" }, { type: "Optional", child: { type: "Sequence", children: [ { type: "Terminal", text: "IF" }, { type: "Terminal", text: "EXISTS" } ] } }, { type: "NonTerminal", text: "@name" }, { type: "Terminal", text: "ON" }, { type: "Choice", index: 1, children: [ { type: "Terminal", text: "ROOT" }, { type: "Terminal", text: "NAMESPACE" }, { type: "Terminal", text: "DATABASE" } ] } ] }
] }
]}
]
};

<RailroadDiagram ast='{"type":"Diagram","padding":[10,20,10,20],"children":[{"type":"Sequence","children":[{"type":"Terminal","text":"REMOVE"},{"type":"Choice","index":1,"children":[{"type":"Sequence","children":[{"type":"Terminal","text":"NAMESPACE"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"DATABASE"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"USER"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"},{"type":"Terminal","text":"ON"},{"type":"Choice","index":1,"children":[{"type":"Terminal","text":"ROOT"},{"type":"Terminal","text":"NAMESPACE"},{"type":"Terminal","text":"DATABASE"}]}]},{"type":"Sequence","children":[{"type":"Terminal","text":"ACCESS"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"},{"type":"Terminal","text":"ON"},{"type":"Choice","index":1,"children":[{"type":"Terminal","text":"NAMESPACE"},{"type":"Terminal","text":"DATABASE"}]}]},{"type":"Sequence","children":[{"type":"Terminal","text":"EVENT"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"},{"type":"Terminal","text":"ON"},{"type":"Optional","child":{"type":"Terminal","text":"TABLE"}},{"type":"NonTerminal","text":"@table"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"FIELD"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"},{"type":"Terminal","text":"ON"},{"type":"Optional","child":{"type":"Terminal","text":"TABLE"}},{"type":"NonTerminal","text":"@table"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"INDEX"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"},{"type":"Terminal","text":"ON"},{"type":"Optional","child":{"type":"Terminal","text":"TABLE"}},{"type":"NonTerminal","text":"@table"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"ANALYZER"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"FUNCTION"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"Terminal","text":"fn::"},{"type":"NonTerminal","text":"@name"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"PARAM"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"Terminal","text":"$"},{"type":"NonTerminal","text":"@name"}]},{"type":"Sequence","children":[{"type":"Terminal","text":"TABLE"},{"type":"Optional","child":{"type":"Sequence","children":[{"type":"Terminal","text":"IF"},{"type":"Terminal","text":"EXISTS"}]}},{"type":"NonTerminal","text":"@name"}]}]}]}]}' />

</TabItem>
</Tabs>

## Example usage

### Basic usage

The following queries show an example of how to remove resources.
Expand Down Expand Up @@ -114,7 +77,6 @@ REMOVE TABLE article;

### Using if exists clause


The following queries show an example of how to remove resources using the `IF EXISTS` clause, which will only remove the resource if it exists.

```surql
Expand Down Expand Up @@ -213,15 +175,15 @@ The `SELECT * FROM pc_agg` query shows that the table view is pulling data from
-------- Query --------

[
{
class: 'Warrior',
count: 10,
id: pc_agg:['Warrior']
},
{
class: 'Wizard',
count: 3,
id: pc_agg:['Wizard']
{
class: 'Warrior',
count: 10,
id: pc_agg:['Warrior']
},
{
class: 'Wizard',
count: 3,
id: pc_agg:['Wizard']
}
]

Expand All @@ -234,10 +196,10 @@ The `SELECT * FROM pc_agg` query shows that the table view is pulling data from

While all `REMOVE` statements remove the definition for a resource, some resources have additional actions when removed. They are:

* REMOVE DATABASE: This effectively deletes the database by removing the index stores, deleting the definition, and clearing the cache.
* REMOVE NAMESPACE: Same as `REMOVE DATABASE`, in addition to performing a remove on each database inside the namespace.
* REMOVE TABLE: Similar to the two previous statements but on a single table, and will fail if a table view depends on it. Removing a table will also send a [KILL](/docs/reference/query-language/statements/kill) notification for each live query defined on it.
* REMOVE INDEX: This statement also removes the index store cache and index data. If you are considering removing an index but want to test the behaviour out first, use an [ALTER INDEX PREPARE REMOVE](/docs/reference/query-language/statements/alter/indexes/#prepare-remove-clause) statement. This will decommission the index, after which you can test out queries to see their behaviour as they would function after the index is removed. If acceptable then the index can then be removed, or the change can be reverted by [rebuilding the index](/docs/reference/query-language/statements/rebuild).
- REMOVE DATABASE: This effectively deletes the database by removing the index stores, deleting the definition, and clearing the cache.
- REMOVE NAMESPACE: Same as `REMOVE DATABASE`, in addition to performing a remove on each database inside the namespace.
- REMOVE TABLE: Similar to the two previous statements but on a single table, and will fail if a table view depends on it. Removing a table will also send a [KILL](/docs/reference/query-language/statements/kill) notification for each live query defined on it.
- REMOVE INDEX: This statement also removes the index store cache and index data. If you are considering removing an index but want to test the behaviour out first, use an [ALTER INDEX PREPARE REMOVE](/docs/reference/query-language/statements/alter/indexes/#prepare-remove-clause) statement. This will decommission the index, after which you can test out queries to see their behaviour as they would function after the index is removed. If acceptable then the index can then be removed, or the change can be reverted by [rebuilding the index](/docs/reference/query-language/statements/rebuild).

Another `REMOVE` statement to note is `REMOVE FIELD`, as it does not remove any existing data. To remove the existing data, perform an `UPDATE` or `UPSERT` statement that uses `UNSET` on the field or sets the field's value to `NONE`.

Expand Down Expand Up @@ -268,4 +230,4 @@ DEFINE FIELD created_at ON person TYPE datetime; -- Define a new field

-- Works because values matche schema: 'name' is set to NONE, 'created_at' has a datetime value
UPDATE person SET name = NONE, created_at = time::now();
```
```