Officially out now: The TypeDB 3.0 Roadmap >>

Define query

A Define query extends the schema of a database with new schema statements. For a practical guide on how to send a Define query to TypeDB, see the Define query page of the TypeDB Manual.

Syntax

A Define query consists of a single define clause and always starts with the define keyword.

Define queries are written in TypeQL with the following syntax:

define <schema_definitions>

where <schema_definitions> are valid schema-specific TypeQL statements: sub / sub!, abstract, owns, value, regex, relates, plays, rule, and annotations: @key and @unique. Schema statements in a define clause can’t use any variables or values, except for rules.

Behavior

A Define query adds schema statements to an existing schema. These statements can add new types and rules, or they can add new properties to existing types and replace existing rules. Define queries can’t change schema statements already existing in a schema, except for annotations and rules.

Query execution

Define queries are idempotent, meaning they can be applied multiple times without changing the result of the initial application.

A Define query must produce a valid schema in a database, otherwise it will be rejected.

Query response

A successful Define query returns a promise of an empty response.

Define types

To define a new type, subtype an existing type with a sub statement. Use owns statements to assign an ability to own attribute types.

For roles on relations, use relates and plays statements.

Simple statements about the same subject can be combined in a composite statement.

Defining types example
define

credential sub attribute, value string;
email sub attribute, value string;
full-name sub attribute, value string;
review-date sub attribute, value datetime;

subject sub entity,
    abstract,
    owns credential,
    plays permission:subject;
user sub subject, abstract;
person sub user,
    owns email,
    owns full-name;

permission sub relation,
    owns review-date,
    relates subject;

The above example defines four attribute types, three entity types, and a single relation type.

Define rules

For this example, use a database with the IAM schema and sample data loaded.

Use a rule statement to define a new rule or replace an existing one:

Defining a rule example
define

rule add-view-permission: when {
    $modify isa action, has name "modify_file";
    $view isa action, has name "view_file";
    $ac_modify (object: $obj, action: $modify) isa access;
    $ac_view (object: $obj, action: $view) isa access;
    (subject: $subj, access: $ac_modify) isa permission;
} then {
    (subject: $subj, access: $ac_view) isa permission;
};

Learn more

Lesson 5: Defining schemas

Learn more about defining a schema in TypeDB Academy.

Define query

See how to send a Define query to TypeDB.