Define query

A Define query extends the schema of a database with new schema statements.

Define queries can be used only in a schema session and write transaction. For more information on the limitations of a schema session, see the Schema integrity enforcement.

For more information about basics of data modeling with TypeQL, see the Fundamentals page.

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. It can’t change schema statements already existing in a schema, except for annotations and rules.

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 consistent and valid schema in a database, otherwise it will not pass validation and will be rejected.

Define query returns a Promise of an empty response.

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 statements>

Schema statements in a define clause use TypeQL to declare type definitions and rules.

For more information on defining rules, see the Rule definitions page. For more information on defining types, ownerships, and roleplayers, see below and the Type definitions.

Define clause

A define clause is used in a Define query to specify schema statements for new or updated types and rules. Schema statements in a define clause can’t use any variables or values.

TypeQL statements are combined by an implicit conjunction (logical AND) so they can be included in a query in any order or even added later with another query with the same result.

Schema statements can use types that already exist in a schema (including built-in types) or defined anywhere in the same query. Every statement ends with a semicolon.

Schema statements can be divided to type statements and rule statements. For more information on type statements, see the Type definitions page. For more information on rule statements, see the Rule definitions page.

Examples

The following examples illustrate the basic syntax of Define queries. For more advanced examples, see the Type definitions and Rule definitions pages.

Define a new type

To define a new type, subtype an existing one.

Defining a type example
define

credential sub attribute, value string;
subject sub entity, owns credential;
user sub subject;

The above example adds three new types:

  • credential — attribute type with string value type.

  • subject — entity type that can own credential attributes.

  • user — entity type that subtypes the subject type and by doing so, inherits the ability to own credential.

Define a new property

To define a new property for an existing type, use a Define query with a statement that states the new property for an existing type.

Defining a property example
define

user owns email;
email sub attribute, value string;

The above query adds a new email attribute type and adds an ownership of it to the existing user type.

Define a relation

To create a new relation, subtype the relation root type or any of its subtypes. To add a role in a relation, use the relates keyword. To enable a type to play a role in a relation, use the plays keyword.

Defining a relation example
define

name sub attribute, value string;

membership sub relation,
    relates member,
    relates parent;

user-group sub subject,
    owns name,
    plays membership:parent;

user plays membership:member;

The above query adds the membership relation type with two roles: member and parent. Then the new user-group type is defined as being able to play the parent role. Finally, the pre-existing user type is modified to be able to play the member role in the membership relation.

Provide Feedback