DDL
DDL short for Data Definition Language is used to create, alter and drop DDL objects such as space
s and model
s.
Generic
USE
- Syntax:
USE <space>
: sets the space that will be used for all other queriesUSE null
: unsets the spaceUSE $current
: returns the name of the space currently set if it still exists or otherwise returns an error
- Access control: any
- Returns: empty or error
DDL actions don't respect
USE
This is so that you're specific about what DDL object you want to manipulate.
Exception: INSPECT
queries will respect the currently set SPACE
if required.
INSPECT:
- Syntax:
INSPECT GLOBAL
: returns a JSON with a list of all spaces, users and other information. For example:{"spaces":["space1"],"users":["root"],"settings":{}}
INSPECT SPACE <space>
: returns a JSON with a list of all models in the space and other information, For example:{"models":["model1"],"properties":{}}
INSPECT MODEL <space>.<model>
: returns a JSON with information about the model such as the declaration, row count and such:{"decl":"{*username: string, !password: string, ?notes: [string]}","size":12345678,"properties":{}}
- Access control: any
- Returns: string or error
Space
CREATE SPACE
Syntax:
-- without any properties
CREATE SPACE [IF NOT EXISTS] <space_name>
-- with properties
CREATE SPACE [IF NOT EXISTS] <space_name> WITH { property_name: property_value }
- Access control:
root
only - Properties: None
- Returns:
- empty or error
- when used with
if not exists
: bool indicating whether the space was actually created or not (false indicates that it was already present and hence not created)
Examples
CREATE SPACE apps
CREATE SPACE IF NOT EXISTS apps
ALTER SPACE
Syntax:
ALTER SPACE <space_name> WITH { property_name: property_value }
- Access control:
root
only - Properties: None
- Returns: empty or error
Examples
ALTER SPACE apps WITH { new_cache_value: 1234 }
DROP SPACE
Syntax:
DROP SPACE [IF EXISTS] [ALLOW NOT EMPTY] <space_name>
- Access control:
root
only - Operational notes:
- A non-empty space cannot be dropped
To avoid catastrophic
DROP
s, aSPACE
can only be dropped directly if it is non-empty. To drop a non-empty space, you must run:DROP SPACE ALLOW NOT EMPTY <space_name>
- A non-empty space cannot be dropped
To avoid catastrophic
- Returns:
- empty or error
- when used with
if exists
: bool indicating whether the space was actually present or not
Examples
DROP SPACE myspace
DROP SPACE ALLOW NOT EMPTY myspace
Models
Type definitions
- When used in create:
- A simple type:
field_name: string
- A list:
field_name: list {type: string}
- A nested list:
field_name: list{type: string}
- A simple type:
- When used in alter:
- A simple type:
field_name { type: string }
- A list:
field_name { type: list {type: string} }
- A nested list:
field_name {type: list{type:list{type:string}}}
- A simple type:
CREATE MODEL
Syntax:
CREATE MODEL [IF NOT EXISTS] <space_name>.<model_name>([primary] [null] field_name: field_type) [ WITH {property_name: property_value} ]
- Access control:
root
only - Properties: None
- Operational notes:
- The first field specified automatically becomes the primary key
- All fields are not nullable by default
- To make a field nullable add the
null
keyword before the field name - If you do not want the first field to become the primary key, then you must add the
primary
keyword before the field that you want to use as the primary key - The field order is preserved. When doing an
INSERT
you will have to supply values in the same order
- Returns:
- empty or error
- when used with
if not exists
: bool indicating whether the model was actually created or not (false indicates that it was already present and hence not created)
Examples
CREATE MODEL myspace.mymodel(username: string, password: string, null email_id: string, notes: list { type: string })
CREATE MODEL IF NOT EXISTS myspace.mymodel(username: string, password: string, null email_id: string, notes: list { type: string })
ALTER MODEL ADD
Syntax:
-- add a single field
ALTER MODEL <space_name>.<model_name> ADD one_field { type: string }
-- add multiple fields
ALTER MODEL <space_name>.<model_name> ADD (
first_field { type: string },
second_field { type: binary },
)
- Access control:
root
only - Returns: empty or error
Examples
ALTER MODEL myspace.mymodel ADD one_field { type: list { type: string } }
ALTER MODEL myspace.mymodel ADD (
email_id: {
type: string,
nullable: true,
},
phone_number: {
type: uint64,
nullable: true,
},
)
ALTER MODEL UPDATE
Syntax
-- update one field
ALTER MODEL <space_name>.<model_name> UPDATE one_field { type: string }
-- update multiple fields
ALTER MODEL <space_name>.<model_name> UPDATE (
first_field { type: string },
second_field { type: binary },
)
- Access control:
root
only - Operational notes
- The primary key field cannot be modified
- Returns: empty or error
Examples
ALTER MODEL myspace.mymodel UPDATE my_int_field { type: uint64 }
ALTER MODEL myspace.mymodel UPDATE (
my_int_field { type: uint64 },
my_float_field { type: float64 }
)
ALTER MODEL REMOVE
Syntax:
-- remove one field
ALTER MODEL <space_name>.<model_name> REMOVE one_field
-- remove multiple fields
ALTER MODEL <space_name>.<model_name> REMOVE (first_field, second_field, ...)
- Access control:
root
only - Operational notes
- The primary key field cannot be removed (as is expected)
- Returns: empty or error
Examples
ALTER MODEL myspace.mymodel REMOVE useless_field
ALTER MODEL myspace.mymodel REMOVE (useless_field_1, useless_field2)
DROP MODEL
Syntax:
DROP MODEL [IF EXISTS] [ALLOW NOT EMPTY] <space_name>.<model_name>
- Access control:
root
only - Operational notes
- Non-empty models cannot be dropped to avoid catastrophic drops
- To drop a non-empty model: you must run:
DROP MODEL ALLOW NOT EMPTY <space_name>.<model_name>
- Returns:
- empty or error
- when used with
if exists
: bool indicating whether the model was actually present or not
Examples
DROP MODEL myspace.mymodel
DROP ALLOW NOT EMPTY myspace.mymodel