131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
## Syntax
|
|
|
|
- [CREATE](https://docs.surrealdb.com/docs/surrealql/statements/select): Creates resources/records, similar to `INSERT INTO` in Postgres
|
|
- [DEFINE](https://docs.surrealdb.com/docs/surrealql/statements/define/overview): Creates namespaces, databases, and scopes, logins
|
|
- [UPDATE](https://docs.surrealdb.com/docs/surrealql/statements/update): Updates resources/records, similar to `UPDATE table_name SET ...` in Postgres
|
|
- [DELETE](https://docs.surrealdb.com/docs/surrealql/statements/delete): Deletes resources/records, similar to `DELETE` in Postgres
|
|
- [USE](https://docs.surrealdb.com/docs/surrealql/statements/use/): Used for switching in between namespaces and databases
|
|
- `SLEEP`: Used to make the database go to sleep
|
|
- `BEGIN`: Used for making a group of SurrealQL statements a singular transaction. Transaction block must end with a `COMMIT`
|
|
- `COMMIT`: Used for making a group of SurrealQL statements a singular transaction. Transaction block must start with a `BEGIN`
|
|
- [RELATE](https://docs.surrealdb.com/docs/surrealql/statements/use/): Used to traverse records efficiently without the need for SQL JOINs
|
|
|
|
## Examples
|
|
|
|
### Basic `SELECT` examples
|
|
|
|
```sql
|
|
-- Select all fields from a table
|
|
SELECT * FROM person;
|
|
|
|
-- Select specific fields from a table
|
|
SELECT name, address, email FROM person;
|
|
|
|
-- Select all fields from a specific record
|
|
SELECT * FROM person:tobie;
|
|
|
|
-- Select specific fields from a specific record
|
|
SELECT name, address, email FROM person:tobie;
|
|
|
|
-- Alias/rename fields
|
|
SELECT name AS user_name, address FROM person;
|
|
|
|
-- Select just a single record
|
|
-- Using the ONLY keyword, just an object for the record in question will be returned.
|
|
-- This, instead of an array with a single object.
|
|
SELECT * FROM ONLY person:john;
|
|
```
|
|
|
|
### Advanced `SELECT` expressions
|
|
|
|
```SQL
|
|
-- Select nested objects/values
|
|
SELECT address.city FROM person;
|
|
|
|
-- Select all nested array values
|
|
-- note the .* syntax works to select everything from an array or object-like values
|
|
SELECT address.*.coordinates AS coordinates FROM person;
|
|
-- Equivalent to
|
|
SELECT address.coordinates AS coordinates FROM person;
|
|
|
|
-- Select one item from an array
|
|
SELECT address.coordinates[0] AS latitude FROM person;
|
|
|
|
-- Select unique values from an array
|
|
SELECT array::distinct(tags) FROM article;
|
|
|
|
-- Select unique values from a nested array across an entire table
|
|
SELECT array::group(tags) AS tags FROM article GROUP ALL;
|
|
|
|
-- Use mathematical calculations in a select expression
|
|
SELECT ( ( celsius * 2 ) + 30 ) AS fahrenheit FROM temperature;
|
|
|
|
-- Return boolean expressions with an alias
|
|
SELECT rating >= 4 as positive FROM review;
|
|
|
|
-- Select manually generated object structure
|
|
SELECT { weekly: false, monthly: true } AS `marketing settings` FROM user;
|
|
|
|
-- Select filtered nested array values
|
|
SELECT address[WHERE active = true] FROM person;
|
|
|
|
-- Select a person who has reacted to a post using a celebration
|
|
-- You can see the graph as: person->(reacted_to WHERE type='celebrate')->post
|
|
SELECT * FROM person WHERE ->(reacted_to WHERE type='celebrate')->post;
|
|
|
|
-- Select a remote field from connected out graph edges
|
|
SELECT ->likes->friend.name AS friends FROM person:tobie;
|
|
|
|
-- Use the result of a subquery as a returned field
|
|
SELECT *, (SELECT * FROM events WHERE type = 'activity' LIMIT 5) AS history FROM user;
|
|
```
|
|
|
|
### Multiple targets with `FROM`
|
|
|
|
```SQL
|
|
-- This command selects all records from both 'user' and 'admin' tables.
|
|
SELECT * FROM user, admin;
|
|
|
|
-- This command selects all records from the table named in the variable '$table',
|
|
-- but only if the 'admin' field of those records is true.
|
|
-- This query is equivalent to 'SELECT * FROM user WHERE admin = true'.
|
|
LET $table = "user";
|
|
SELECT * FROM type::table($table) WHERE admin = true;
|
|
|
|
-- This command selects a single record from:
|
|
-- * the table named in the variable '$table',
|
|
-- * and the identifier named in the variable '$id'.
|
|
-- This query is equivalent to 'SELECT * FROM user:admin'.
|
|
LET $table = "user";
|
|
LET $id = "admin";
|
|
SELECT * FROM type::thing($table, $id);
|
|
```
|
|
### `UPDATE` examples
|
|
|
|
```SQL
|
|
-- Update all records in a table
|
|
UPDATE person SET skills += ['breathing'];
|
|
|
|
-- Update or create a record with a specific numeric id
|
|
UPDATE person:100 SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
|
|
|
|
-- Update or create a record with a specific string id
|
|
UPDATE person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
|
|
|
|
-- Update just a single record
|
|
-- Using the ONLY keyword, just an object for the record in question will be returned.
|
|
-- This, instead of an array with a single object.
|
|
UPDATE ONLY person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
|
|
```
|
|
|
|
### Logins
|
|
Create a login table
|
|
`DEFINE TABLE user SCHEMAFULL PERMISSIONS FOR select, update, delete WHERE id = $auth.id;`
|
|
|
|
Define some fields
|
|
`DEFINE FIELD name ON user TYPE string ASSERT string::len($value) >= 2;`
|
|
`DEFINE FIELD username ON user TYPE string VALUE string::lowercase($value);`
|
|
`DEFINE FIELD password ON user TYPE string PERMISSIONS FOR select NONE;`
|
|
|
|
Create the login
|
|
`DEFINE SCOPE user SESSION 7d SIGNIN ( SELECT * FROM user WHERE username = $username AND crypto::argon2::compare(password, $password) ) SIGNUP ( CREATE user CONTENT { name: $name, username: $username, password: crypto::argon2::generate($password) } );` |