Define query

In this guide, you’ll see how to use a Define query to define types and rules in a database schema using Studio, Console, or one of the drivers.

Understanding Define queries

A Define query is used to define the schema of a database or replace existing parts of the schema. For a detailed explanation of the query see the Define query page. For an alternative way of editing your schema, see the Schema editing page.

Sending Define queries

Before you begin, ensure you have following the Connecting to TypeDB section pages. The easiest way to send a Define query is to use Studio or Console:

Studio
Console

Follow the Studio manual to connect to TypeDB and select a project folder. Then use the steps below:

Use a drop-down list in the top toolbar to select a database.
Switch to schema session and write transaction types.

Open a new tab and insert or type in a Define query, for example:

TypeQL Define query

define

email sub attribute, value string;
name sub attribute, value string;
friendship sub relation, relates friend;
user sub entity,
    owns email @key,
    owns name,
    plays friendship:friend;
admin sub user;

Run the query by clicking the Run Query button.
Commit the changes by clicking the Commit query button.

Follow the Connect to server guide to connect to TypeDB. Then use the steps below:

Open a schema session and write transaction to the selected database (e.g., sample_db):
```
transaction sample_db schema write
```

Send the Define query:

define
email sub attribute, value string;
name sub attribute, value string;
friendship sub relation, relates friend;
user sub entity,
    owns email @key,
    owns name,
    plays friendship:friend;
admin sub user;

Push Enter twice to send the query.

Commit the changes:
```
commit
```

To send a Define query programmatically, use drivers:

Follow the connection guide to connect the driver to TypeDB Cloud or TypeDB Core, then open a schema session to the selected database, open a write transaction, and use the transaction.query().define() method:

let databases = DatabaseManager::new(driver);
let db = databases.get(DB_NAME)?;
{
    let session = Session::new(db, SessionType::Schema)?;
    {
        let tx = session.transaction(TransactionType::Write)?;
        let define_query = "
                            define
                            email sub attribute, value string;
                            name sub attribute, value string;
                            friendship sub relation, relates friend;
                            user sub entity,
                                owns email @key,
                                owns name,
                                plays friendship:friend;
                            admin sub user;
                            ";
        tx.query().define(define_query).resolve()?;
        tx.commit().resolve()?;
    }
}

with driver.session(DB_NAME, SessionType.SCHEMA) as session:
    with session.transaction(TransactionType.WRITE) as tx:
        define_query = """
                        define
                        email sub attribute, value string;
                        name sub attribute, value string;
                        friendship sub relation, relates friend;
                        user sub entity,
                            owns email @key,
                            owns name,
                            plays friendship:friend;
                        admin sub user;
                        """
        tx.query.define(define_query).resolve()
        tx.commit()

try {
    session = await driver.session(DB_NAME, SessionType.SCHEMA);
    try {
        tx = await session.transaction(TransactionType.WRITE);
        const define_query = `
                            define
                            email sub attribute, value string;
                            name sub attribute, value string;
                            friendship sub relation, relates friend;
                            user sub entity,
                                owns email @key,
                                owns name,
                                plays friendship:friend;
                            admin sub user;
                            `;
        await tx.query.define(define_query);
        await tx.commit();
    }
    finally {if (tx.isOpen()) {await tx.close()};}
}
finally {await session?.close();}

try (TypeDBSession session = driver.session(DB_NAME, TypeDBSession.Type.SCHEMA)) {
    try (TypeDBTransaction tx = session.transaction(TypeDBTransaction.Type.WRITE)) {
        String defineQuery = """
                            define
                            email sub attribute, value string;
                            name sub attribute, value string;
                            friendship sub relation, relates friend;
                            user sub entity,
                                owns email @key,
                                owns name,
                                plays friendship:friend;
                            admin sub user;
                            """;
        tx.query().define(defineQuery).resolve();
        tx.commit();
    }
}

using (ITypeDBSession session = driver.Session(DB_NAME, SessionType.Schema)) {
    using (ITypeDBTransaction tx = session.Transaction(TransactionType.Write)) {
        string define_query = @"
                    define
                    email sub attribute, value string;
                    name sub attribute, value string;
                    friendship sub relation, relates friend;
                    user sub entity,
                        owns email @key,
                        owns name,
                        plays friendship:friend;
                    admin sub user;
                    ";
        tx.Query.Define(define_query).Resolve();
        tx.Commit();
    }
}

TypeDB::Options options;
TypeDB::Session session = driver.session(DB_NAME, TypeDB::SessionType::SCHEMA, options);
{
    TypeDB::Transaction tx = session.transaction(TypeDB::TransactionType::WRITE, options);
    std::string defineQuery = R"(
                        define
                        email sub attribute, value string;
                        name sub attribute, value string;
                        friendship sub relation, relates friend;
                        user sub entity,
                            owns email @key,
                            owns name,
                            plays friendship:friend;
                        admin sub user;
                        )";
    tx.query.define(defineQuery).get();
    tx.commit();
}

Options* opts = options_new();
session = session_new(databaseManager, DB_NAME, Schema, opts);
tx = transaction_new(session, Write, opts);
if (tx == NULL || FAILED()) {
    handle_error("Transaction failed to start.");
    goto cleanup;
}
char query[512];
snprintf(query, sizeof(query), "define email sub attribute, value string; name sub attribute, value string; friendship sub relation, relates friend; user sub entity, owns email @key, owns name, plays friendship:friend; admin sub user;");
void_promise_resolve(query_define(tx, query, opts));
if (FAILED()) {
    handle_error("Query execution failed.");
    goto cleanup;
}
void_promise_resolve(transaction_commit(tx));
if (FAILED()) {
    handle_error("Transaction commit failed.");
    goto cleanup;
}
session_close(session);

Response interpretation

A Define query returns a Promise of an empty response. This promise can be resolved when the query is finished executing, but it doesn’t contain any useful information.

Learn more

Define query

Learn more about Define queries in TypeQL: syntax, behavior, and query examples.

Writing data

Learn how to write some data to a database with the schema you just defined.

Lesson 5: Defining schemas

Check out the Defining schemas section of TypeDB Academy.