DDL

DDL short for Data Definition Language is used to create, alter and drop DDL objects such asspaces andmodels.

Generic​

USE​

• Syntax:
  • USE <space>: sets the space that will be used for all other queries
  • USE null: unsets the space
  • USE $current: returns the name of the space currently setif it still exists or otherwise returns an error
• Access control: any
• Returns: empty or error

DDL actions don’t respectUSE

This is so that you’re specific about what DDL object you want to manipulate.

Exception:INSPECT queries will respect the currently setSPACE 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 propertiesCREATE SPACE [IF NOT EXISTS] <space_name>-- with propertiesCREATE SPACE [IF NOT EXISTS] <space_name> WITH { property_name: property_value }

• Access control:root only
• Properties: None
• Returns:
  • empty or error
  • when used withif 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 appsCREATE 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 catastrophicDROPs, aSPACE can only be dropped directly if it is empty. To drop a non-empty space, you must run:

    DROP SPACE ALLOW NOT EMPTY <space_name>

• Returns:

  • empty or error
  • when used withif exists: bool indicating whether the space was actually present or not

Examples​

DROP SPACE myspaceDROP 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}
• 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}}}

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:
  • Thefirst field specified automatically becomes the primary key
  • Allfields are not nullable by default
  • To make a field nullable add thenull keyword before the field name
  • If you do not want the first field to become the primary key, then you must add theprimary keyword before the field that you want to use as the primary key
  • The field order is preserved. When doing anINSERT you will have to supply values in the same order
• Returns:
  • empty or error
  • when used withif 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 fieldALTER MODEL <space_name>.<model_name> ADD one_field { type: string }-- add multiple fieldsALTER 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 fieldALTER MODEL <space_name>.<model_name> UPDATE one_field { type: string }-- update multiple fieldsALTER 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 fieldALTER MODEL <space_name>.<model_name> REMOVE one_field-- remove multiple fieldsALTER 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_fieldALTER 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 withif exists: bool indicating whether the model was actually present or not

Examples​

DROP MODEL myspace.mymodelDROP ALLOW NOT EMPTY myspace.mymodel

TRUNCATE MODEL​

TRUNCATE MODEL <space_name>.<model_name>

• Access control:root only
• Operational notes:
  • Blocking
  • Blocks all DML queries until completion of execution
• Returns:
  • empty or error

Examples​

TRUNCATE MODEL myspace.mymodel