Skip to content
Merged
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
66 changes: 65 additions & 1 deletion src/content/doc-surrealql/statements/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ title: Statements | SurrealQL
description: Statements are used to configure and query a database.
---

import Since from '@components/shared/Since.astro'

# Statements

SurrealDB has a variety of statements that let you configure and query a database. In this section, we'll look at the different types of statements that are available.
Expand Down Expand Up @@ -86,4 +88,66 @@ A number of parameters prefixed with `$` are automatically available within a st
* [$session](/docs/surrealql/parameters#session) provides context on the current session,
* [$parent](/docs/surrealql/parameters#parent-this) provides access to the value in a primary query while inside a subquery.

For a full list of these automatically generated parameters, see the [parameters](/docs/surrealql/parameters#reserved-variable-names) page.
For a full list of these automatically generated parameters, see the [parameters](/docs/surrealql/parameters#reserved-variable-names) page.

## Output when resource not defined

<Since v="v3.0.0-beta.1" />

Many but not all statements in versions before 3.0 returned an empty array when a resource was not defined.

```surql
SELECT * FROM person;
DELETE person;
REMOVE TABLE person;
```

```surql title="Output before 3.0"
-------- Query 1 --------

[]

-------- Query 2 --------

[]

-------- Query 3 --------

"The table 'person' does not exist"
```

All statements return an error if this is the case, making it clear that the resource is not defined as opposed to defined and empty.

```surql
SELECT * FROM person;
DELETE person;
```

```surql title="Output"
-------- Query --------

"The table 'person' does not exist"

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

"The table 'person' does not exist"
```

However, statements that create a resource will not return an error unless the [database is defined](/docs/surrealql/statements/define/database) as `STRICT`. Instead, they will automatically define the needed table (and even use the [`$session`](/docs/surrealdb/security/authentication#session) parameter to define the database and namespace if necessary) so that the query will work.

Note the output of the following queries, in which the value `[]` is returned after deleting the records of a defined table to show that zero records were returned. However, the final `REMOVE TABLE` statement returns a simple `NONE` to indicate that the statement succeeded.

```surql
SELECT * FROM person; -- Error
DELETE person; -- Error
CREATE person:one; -- Succeeds
DELETE person; -- Empty array
REMOVE TABLE person; -- NONE
```

The following chart can help to remember which output to expect depending on your SurrealDB version and database strictness.

| Example of statement | STRICT database | Non-STRICT database behavior (default) | Behavior in versions < 3.0 |
|-----------------------|----------------------|------------------------------------------------------------|----------------------------------|
| CREATE / UPDATE | Error if not defined | Succeeds (defines table, database, namespace if necessary) | Identical |
| SELECT / DELETE | Error if not defined | Returns error if table not defined | Empty array if table not defined |