DDL

DDL short for Data Definition Language is used to create, alter and drop DDL objects such as spaces and models.

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 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 DROPs, a SPACE 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>
• 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}
• 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:
  • 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