diff --git a/versioned_docs/version-nightly/surrealql/statements/define/analyzer.mdx b/versioned_docs/version-nightly/surrealql/statements/define/analyzer.mdx index ee7d04bd0..89507711e 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/analyzer.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/analyzer.mdx @@ -15,9 +15,10 @@ In the context of a database, an analyzer plays a crucial role in text processin ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE ANALYZER @name [ TOKENIZERS @tokenizers ] [ FILTERS @filters ] +DEFINE ANALYZER [IF NOT EXISTS] @name [ TOKENIZERS @tokenizers ] [ FILTERS @filters ] ``` + ## Tokenizers Tokenizers are responsible for breaking down a given text into individual tokens based on a set of instructions. There are a couple of tokenizers that can be used while defining an analyzer as seen below: @@ -126,6 +127,15 @@ For example, if you had the text **"Hello World"**, the uppercase filter would c DEFINE ANALYZER example_uppercase TOKENIZERS class FILTERS uppercase; ``` +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to create an analyzer only if it does not already exist. If the analyzer already exists, the `DEFINE ANALYZER` statement will return an error. + +```surql +-- Create a ANALYZER if it does not already exist +DEFINE ANALYZER IF NOT EXISTS example TOKENIZERS blank; +``` + ## More examples Examples on application of analyzers to indexes can be found in the documenation on [`DEFINE INDEX`](/docs/surrealdb/nightly/surrealql/statements/define/indexes) statement diff --git a/versioned_docs/version-nightly/surrealql/statements/define/database.mdx b/versioned_docs/version-nightly/surrealql/statements/define/database.mdx index 026c10007..296a27ddb 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/database.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/database.mdx @@ -26,4 +26,13 @@ Below shows how you can create a database using the DEFINE DATABASE statement. USE NS abcum; -- Define database DEFINE DATABASE app_vitalsense; -``` \ No newline at end of file +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a database only if it does not already exist. If the database already exists, the `DEFINE DATABASE` statement will return an error. + +```surql +-- Create a DATABASE if it does not already exist +DEFINE DATABASE IF NOT EXISTS app_vitalsense; +``` diff --git a/versioned_docs/version-nightly/surrealql/statements/define/event.mdx b/versioned_docs/version-nightly/surrealql/statements/define/event.mdx index 40379518f..290835894 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/event.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/event.mdx @@ -15,7 +15,7 @@ Events can be triggered after any change or modification to the data in a record ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE EVENT @name ON [ TABLE ] @table [ WHEN @expression ] THEN @expression +DEFINE EVENT [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ WHEN @expression ] THEN @expression ``` ## Example usage @@ -72,4 +72,13 @@ DEFINE EVENT user_deleted ON TABLE user WHEN $event = "DELETE" THEN ( DEFINE EVENT user_event ON TABLE user WHEN $event = "CREATE" OR $event = "UPDATE" OR $event = "DELETE" THEN ( CREATE log SET table = "user", event = $event, created_at = time::now() ); +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define an event only if it does not already exist. If the event already exists, the `DEFINE EVENT` statement will return an error. + +```surql +-- Create a EVENT if it does not already exist +DEFINE EVENT IF NOT EXISTS example ON example THEN {}; ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/field.mdx b/versioned_docs/version-nightly/surrealql/statements/define/field.mdx index 8b9c00c44..544e88a80 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/field.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/field.mdx @@ -10,12 +10,12 @@ The `DEFINE FIELD` statement allows you to instantiate a named field on a table, ## Requirements - You must be authenticated as a root or namespace user before you can use the `DEFINE FIELD` statement. -- [You must select your namespace and database](/docs/surrealdb/surrealql/statements/use) before you can use the `DEFINE FIELD` statement. +- [You must select your namespace and database](/docs/surrealdb/nightly/surrealql/statements/use) before you can use the `DEFINE FIELD` statement. ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE FIELD @name ON [ TABLE ] @table +DEFINE FIELD [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ [ FLEXIBLE ] TYPE @type ] [ DEFAULT @expression ] [ READONLY ] @@ -39,7 +39,7 @@ DEFINE FIELD email ON TABLE user; ``` ## Defining data types -The `DEFINE FIELD` statement allows you to set the data type of a field. For a full list of supported data types, see [Data types](/docs/surrealdb/surrealql/datamodel/overview). +The `DEFINE FIELD` statement allows you to set the data type of a field. For a full list of supported data types, see [Data types](/docs/surrealdb/nightly/surrealql/datamodel/overview). ### Simple data types ```surql @@ -65,6 +65,9 @@ DEFINE FIELD metadata ON TABLE user FLEXIBLE TYPE object; ``` ### Array type + +You can also set a field to have the array data type. The array data type can be used to store a list of values. You can also set the data type of the array's contents. + ```surql -- Set a field to have the array data type DEFINE FIELD roles ON TABLE user TYPE array; @@ -80,13 +83,24 @@ DEFINE FIELD posts.* ON TABLE user TYPE record; ``` ### Making a field optional +You can make a field optional by wrapping the inner type in an `option`, which allows you to store `NONE` values in the field. + ```surql -- A user may enter a biography, but it is not required. -- By using the option type you also allow for NONE values. DEFINE FIELD biography ON TABLE user TYPE option; ``` + +The example below shows how to define a field `user` on a `POST` table. The field is of type [record](/docs/surrealdb/nightly/surrealql/datamodel/overview). This means that the field can store a `record` or `NONE`. + +```surql +DEFINE FIELD user ON TABLE POST TYPE option>; +``` + ### Setting a default value +You can set a default value for a field using the `DEFAULT` clause. The default value will be used if no value is provided for the field. + ```surql -- A user is not locked by default. DEFINE FIELD locked ON TABLE user TYPE bool @@ -94,7 +108,7 @@ DEFINE FIELD locked ON TABLE user TYPE bool DEFAULT false; ``` -#### `DEFAULT` inherited from `VALUE` +### `DEFAULT` inherited from `VALUE` If the `VALUE` clause contains a static query, meaning not depending on any variables, and in case no `DEFAULT` clause is specified, then the `VALUE` clause will be used as the `DEFAULT` clause aswell. @@ -104,6 +118,9 @@ DEFINE FIELD updated ON resource VALUE time::now(); ### Alter a passed value +You can alter a passed value using the `VALUE` clause. This is useful for altering the value of a field before it is stored in the database. +In the example below, the `VALUE` clause is used to ensure that the email address is always stored in lowercase characters by using the [`string::lowercase`](/docs/surrealdb/nightly/surrealql/functions/string#stringlowercase) function. + ```surql -- Ensure that an email address is always stored in lowercase characters DEFINE FIELD email ON TABLE user TYPE string @@ -112,7 +129,7 @@ DEFINE FIELD email ON TABLE user TYPE string ## Asserting rules on fields -You can take your field definitions even further by using asserts. Assert is a powerful feature that can be used to ensure that your data remains consistent. +You can take your field definitions even further by using asserts. Assert can be used to ensure that your data remains consistent. For example you can use asserts to ensure that a field is always a valid email address, or that a number is always positive. ### Email is required @@ -125,12 +142,39 @@ DEFINE FIELD email ON TABLE user TYPE string ### Making a field `READONLY` +The `READONLY` clause can be used to prevent any updates to a field. This is useful for fields that are automatically updated by the system. To make a field `READONLY`, add the `READONLY` clause to the `DEFINE FIELD` statement. As seen in the example below, the `created` field is set to `READONLY`. + ```surql DEFINE FIELD created ON resource VALUE time::now() READONLY; ``` +### Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to create a field only if it does not already exist. If the field already exists, the `DEFINE FIELD` statement will not create a new field but return an error. + +```surql +-- Create a field if it does not already exist +DEFINE FIELD IF NOT EXISTS email ON TABLE user TYPE string; +``` + + +### Setting permissions on fields + +You can set permissions on fields to control who can perform operations on them using the `PERMISSIONS` clause. The `PERMISSIONS` clause can be used to set permissions for `SELECT`, `CREATE`, `UPDATE`, and `DELETE` operations. + +```surql +-- Set permissions for the email field +DEFINE FIELD email ON TABLE user + PERMISSIONS + FOR select WHERE published=true OR user=$auth.id + FOR update WHERE user=$auth.id + FOR delete WHERE user=$auth.id OR $auth.role="admin"; +``` + +The `PERMISSIONS` clause can also be used to set permissions for all operations using the `FULL` keyword. + ## Array with allowed values -By using an Access Control List as an example we can show how we can restrict what values can be stored in an array. +By using an Access Control List as an example we can show how we can restrict what values can be stored in an array. In this example we are using an array to store the permissions for a user on a resource. The permissions are restricted to a specific set of values. ```surql -- An ACL can be applied to any kind of resource (record) @@ -177,6 +221,8 @@ CREATE acl SET ``` ## Using RegEX to validate a string +You can use the `ASSERT` clause to apply a regular expression to a field to ensure that it matches a specific pattern. In the example below, the `ASSERT` clause is used to ensure that the `countrycode` field is always a valid ISO-3166 country code. + ```surql -- Specify a field on the user table DEFINE FIELD countrycode ON user TYPE string diff --git a/versioned_docs/version-nightly/surrealql/statements/define/function.mdx b/versioned_docs/version-nightly/surrealql/statements/define/function.mdx index 0666a88db..07d1b040a 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/function.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/function.mdx @@ -15,7 +15,7 @@ The `DEFINE FUNCTION` statement allows you to define custom functions that can b ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE FUNCTION fn::@name( +DEFINE FUNCTION [ IF NOT EXISTS ] fn::@name( [ @argument: @type ... ] ) { [ @query ... ] @@ -71,4 +71,13 @@ RETURN fn::last_option(1); required_present: true, optional_present: false, }; +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a function only if it does not already exist. If the function already exists, the `DEFINE FUNCTION` statement will return an error. + +```surql +-- Create a FUNCTION if it does not already exist +DEFINE FUNCTION IF NOT EXISTS fn::example() {}; ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/indexes.mdx b/versioned_docs/version-nightly/surrealql/statements/define/indexes.mdx index 1e1fa4a19..3d3e964c0 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/indexes.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/indexes.mdx @@ -15,7 +15,7 @@ Just like in other databases, SurrealDB uses indexes to help optimize query perf ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE INDEX @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields +DEFINE INDEX [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields [ UNIQUE | SEARCH ANALYZER @analyzer [ BM25 [(@k1, @b)] ] [ HIGHLIGHTS ] ] ``` ## Index Types @@ -155,6 +155,17 @@ It also reveals details about which `operation` was used by the query planner an } ] ``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a index only if it does not already exist. If the index already exists, the `DEFINE INDEX` statement will return an error. + +```surql +-- Create a INDEX if it does not already exist +DEFINE INDEX IF NOT EXISTS example ON example FIELDS example; + +``` + ## Performance Implications When defining indexes, it's essential to consider the fields most frequently queried or used to optimize performance. diff --git a/versioned_docs/version-nightly/surrealql/statements/define/namespace.mdx b/versioned_docs/version-nightly/surrealql/statements/define/namespace.mdx index b1796b562..41f4c3f97 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/namespace.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/namespace.mdx @@ -16,7 +16,7 @@ Let's say that you're using SurrealDB to create a multi-tenant SaaS application. ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE NAMESPACE @name +DEFINE NAMESPACE [IF NOT EXISTS] @name ``` ## Example usage @@ -25,4 +25,13 @@ Below shows how you can create a namespace using the `DEFINE NAMESPACE` statemen ```surql -- Namespace for Abcum Ltd. DEFINE NAMESPACE abcum; +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a namespace only if it does not already exist. If the namespace already exists, the `DEFINE NAMESPACE` statement will return an error. + +```surql +-- Create a NAMESPACE if it does not already exist +DEFINE NAMESPACE IF NOT EXISTS example; ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/overview.mdx b/versioned_docs/version-nightly/surrealql/statements/define/overview.mdx index 742a3a9a3..dd556c1d4 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/overview.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/overview.mdx @@ -10,15 +10,15 @@ The DEFINE statement can be used to specify authentication access and behaviour, ```surql title="SurrealQL Syntax" DEFINE [ - NAMESPACE @name - | DATABASE @name - | USER @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles - | TOKEN @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value - | SCOPE @name + NAMESPACE [ IF NOT EXISTS ] @name + | DATABASE [ IF NOT EXISTS ] @name + | USER [ IF NOT EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles + | TOKEN [ IF NOT EXISTS ] @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value + | SCOPE [ IF NOT EXISTS ] @name [ SESSION @duration ] [ SIGNUP @expression ] [ SIGNIN @expression ] - | TABLE @name + | TABLE [ IF NOT EXISTS ] @name [ DROP ] [ SCHEMAFULL | SCHEMALESS ] [ AS SELECT @projections @@ -32,8 +32,8 @@ DEFINE [ | FOR update @expression | FOR delete @expression ] ] - | EVENT @name ON [ TABLE ] @table WHEN @expression THEN @expression - | FIELD @name ON [ TABLE ] @table + | EVENT [ IF NOT EXISTS ] @name ON [ TABLE ] @table WHEN @expression THEN @expression + | FIELD [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ [ FLEXIBLE ] TYPE @type ] [ VALUE @expression ] [ ASSERT @expression ] @@ -43,10 +43,12 @@ DEFINE [ | FOR update @expression | FOR delete @expression ] ] - | ANALYZER @name + | PARAM [ IF NOT EXISTS ] $@name VALUE @value + | FUNCTION [ IF NOT EXISTS ] fn::@name ( [ ( @argument:@type ... ) ] ) { [@query] [RETURNS @returned] } + | ANALYZER [ IF NOT EXISTS ] @name [ TOKENIZERS @tokenizers ] [ FILTERS @filters ] - | INDEX @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields + | INDEX [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields [ UNIQUE | SEARCH ANALYZER @analyzer [ BM25 [(@k1, @b)] ] [ HIGHLIGHTS ] ] ] ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/param.mdx b/versioned_docs/version-nightly/surrealql/statements/define/param.mdx index 378ace2fa..3e8129553 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/param.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/param.mdx @@ -15,7 +15,7 @@ The `DEFINE PARAM` statement allows you to define global (database-wide) paramet ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE PARAM $@name VALUE @value; +DEFINE PARAM [IF NOT EXISTS] $@name VALUE @value; ``` ## Example usage @@ -28,4 +28,13 @@ Then, simply use the global parameter like you would with any variable. ```surql RETURN http::get($endpointBase + "/products"); +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a param only if it does not already exist. If the param already exists, the `DEFINE PARAM` statement will return an error. + +```surql +-- Create a PARAM if it does not already exist +DEFINE PARAM IF NOT EXISTS $example VALUE 123; ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/scope.mdx b/versioned_docs/version-nightly/surrealql/statements/define/scope.mdx index b2b042c23..b05c4f0d3 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/scope.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/scope.mdx @@ -15,7 +15,7 @@ Setting scope access allows SurrealDB to operate as a web database. With scopes ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE SCOPE @name SESSION @duration SIGNUP @expression SIGNIN @expression +DEFINE SCOPE [ IF NOT EXISTS ] @name SESSION @duration SIGNUP @expression SIGNIN @expression ``` ## Example usage @@ -27,4 +27,13 @@ DEFINE SCOPE account SESSION 24h SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) ) SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) ) ; +``` + +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a scope only if it does not already exist. If the scope already exists, the `DEFINE SCOPE` statement will return an error. + +```surql +-- Create a SCOPE if it does not already exist +DEFINE SCOPE IF NOT EXISTS example; ``` \ No newline at end of file diff --git a/versioned_docs/version-nightly/surrealql/statements/define/table.mdx b/versioned_docs/version-nightly/surrealql/statements/define/table.mdx index 5ca2511c6..d6561b13a 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/table.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/table.mdx @@ -15,7 +15,7 @@ The `DEFINE TABLE` statement allows you to declare your table by name, enabling ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE TABLE @name +DEFINE TABLE [ IF NOT EXISTS ] @name [ DROP ] [ SCHEMAFULL | SCHEMALESS ] [ AS SELECT @projections @@ -55,6 +55,15 @@ The following expression shows how you can define a `CHANGEFEED` for a table. Yo DEFINE TABLE reading CHANGEFEED 1d; ``` +### Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a table only if it does not already exist. If the table already exists, the `DEFINE TABLE` statement will return an error. + +```surql +-- Create a TABLE if it does not already exist +DEFINE TABLE IF NOT EXISTS reading +``` + ### Schemafull tables The following example demonstrates the `SCHEMAFULL` portion of the `DEFINE TABLE` statement. When a table is defined as schemafull, the database strictly enforces any schema definitions that are specified using the `DEFINE TABLE` statement. New fields can not be added to a `SCHEMAFULL` table unless they are defined via the [`DEFINE FIELD`](/docs/surrealdb/surrealql/statements/define/field) statement. diff --git a/versioned_docs/version-nightly/surrealql/statements/define/token.mdx b/versioned_docs/version-nightly/surrealql/statements/define/token.mdx index e5c51b2dc..dabe2fb2d 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/token.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/token.mdx @@ -11,7 +11,7 @@ SurrealDB can work with third-party authentication providers such as OpenID Conn This verification is performed automatically by SurrealDB when provided with a JWT through any of its interfaces (i.e. the [HTTP REST API](/docs/surrealdb/Integration/http) through the “Authorization” header or [any of the SDKs](/docs/surrealdb/nightly/integration/sdks/overview) through the “Authenticate” methods) before trusting the claims contained in the token and allowing SurrealQL queries to access the values of those claims. ```surql title="SurrealQL Syntax" -DEFINE TOKEN @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value +DEFINE TOKEN [ IF NOT EXISTS ] @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value ``` ## Verification Types @@ -102,6 +102,15 @@ To avoid performing requests to the remote URL for each token that is verified, - To `DEFINE TOKEN ... ON SCOPE ...` you must have root, namespace, or database level access. - [You must select your namespace and/or database](/docs/surrealdb/surrealql/statements/use) before you can use the `DEFINE DATABASE` statement for database or namespace tokens. +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a token only if it does not already exist. If the token already exists, the `DEFINE TOKEN` statement will return an error. + +```surql +-- Create a TOKEN if it does not already exist +DEFINE TOKEN example ON SCOPE example TYPE HS512 VALUE "example"; +``` + ## Using Tokens The `DEFINE TOKEN` statement lets you specify the amount of permission granting authority you want to give to a token issuer. You are able to specify if the provider can grant namespace, database, or scope level access to token holders. For this to work, the JWT issued to be used with SurrealDB must contain claims to specify which namespace, database or scope the token bearer is authorized to act on. diff --git a/versioned_docs/version-nightly/surrealql/statements/define/user.mdx b/versioned_docs/version-nightly/surrealql/statements/define/user.mdx index 974becdbe..069ffd2b1 100644 --- a/versioned_docs/version-nightly/surrealql/statements/define/user.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/define/user.mdx @@ -30,7 +30,7 @@ Use the `DEFINE USER` statement to create system users on SurrealDB ## Statement syntax ```surql title="SurrealQL Syntax" -DEFINE USER @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles +DEFINE USER [ IF NOT EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles ``` ## Example usage @@ -57,6 +57,15 @@ USE NS abcum DB app_vitalsense; DEFINE USER username ON DATABASE PASSWORD '123456' ROLES OWNER; ``` +## Using `IF NOT EXISTS` clause + +The `IF NOT EXISTS` clause can be used to define a user only if it does not already exist. If the user already exists, the `DEFINE USER` statement will return an error. + +```surql +-- Create a USER if it does not already exist +DEFINE USER example ON ROOT PASSWORD "example" ROLES OWNER; +``` + ## Roles Currently, only the built-in roles OWNER, EDITOR and VIEWER are available. diff --git a/versioned_docs/version-nightly/surrealql/statements/remove.mdx b/versioned_docs/version-nightly/surrealql/statements/remove.mdx index cffb6dd6f..d8e858aa4 100644 --- a/versioned_docs/version-nightly/surrealql/statements/remove.mdx +++ b/versioned_docs/version-nightly/surrealql/statements/remove.mdx @@ -13,18 +13,18 @@ Similar to an SQL DROP statement. ```surql title="SurrealQL Syntax" REMOVE [ - NAMESPACE @name - | DATABASE @name - | USER @name ON [ ROOT | NAMESPACE | DATABASE ] - | TOKEN @name ON [ NAMESPACE | DATABASE ] - | EVENT @name ON [ TABLE ] @table - | FIELD @name ON [ TABLE ] @table - | INDEX @name ON [ TABLE ] @table - | ANALYZER @name - | FUNCTION fn::@name - | PARAM $@name - | SCOPE @name - | TABLE @name + NAMESPACE [IF EXISTS] @name + | DATABASE[IF EXISTS] @name + | USER [IF EXISTS] @name ON [ ROOT | NAMESPACE | DATABASE ] + | TOKEN [IF EXISTS] @name ON [ NAMESPACE | DATABASE ] + | EVENT [IF EXISTS] @name ON [ TABLE ] @table + | FIELD [IF EXISTS] @name ON [ TABLE ] @table + | INDEX [IF EXISTS] @name ON [ TABLE ] @table + | ANALYZER [IF EXISTS] @name + | FUNCTION [IF EXISTS] fn::@name + | PARAM [IF EXISTS] $@name + | SCOPE [IF EXISTS] @name + | TABLE [IF EXISTS] @name ] ``` @@ -62,3 +62,38 @@ REMOVE SCOPE documentation; 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 +REMOVE NAMESPACE IF EXISTS surrealdb; + +REMOVE DATABASE IF EXISTS blog; + +REMOVE USER IF EXISTS writer ON NAMESPACE; + +REMOVE USER IF EXISTS writer ON DATABASE; + +REMOVE TOKEN IF EXISTS writer_token ON NAMESPACE; + +REMOVE EVENT IF EXISTS new_post ON TABLE article; + +-- Only works for Schemaful tables (i.e. tables with a schema) +REMOVE FIELD IF EXISTS tags ON TABLE article; + +REMOVE INDEX IF EXISTS authors ON TABLE article; + +REMOVE ANALYZER IF EXISTS example_ascii; + +REMOVE FUNCTION IF EXISTS fn::update_author; + +REMOVE PARAM IF EXISTS $author; + +REMOVE SCOPE IF EXISTS documentation; + +REMOVE TABLE IF EXISTS article; + +``` +