TypeDB Console
TypeDB Console is a standalone TypeDB client with a command line interface (CLI).
It is the default client distributed with TypeDB, but it can also be installed separately. For a standalone installation, see the Install page.
Connect to TypeDB
TypeDB can connect to both TypeDB Cloud and TypeDB Core.
Running TypeDB Console initiates a network connection to a TypeDB server.
By default, it tries to connect to a TypeDB Core server at the address localhost:1729
.
Use command line arguments to set connection parameters:
-
Cloud
-
Core
typedb console --cloud=<server-address> --username=<username> --password --tls-enabled=true
You will be prompted for a password.
For newly created deployments, the default username and password are |
typedb console --core=<server-address>
The --core
argument is used to set the TypeDB Core server IP address and port to connect to,
for example, 10.0.0.5:1729
.
As a result, you get a welcome message from TypeDB Console followed by a command line prompt.
Welcome to TypeDB Console. You are now in TypeDB Wonderland! Copyright (C) 2024 TypeDB >
See full list of available CLI arguments in the Console CLI arguments reference section below.
Interactive mode
TypeDB Console provides two levels of interaction via Read–eval–print loop (REPL): Server level and Transaction level.
At any level you can use common commands: help
, clear
, exit
.
Server level
Server level is the first level of interaction, i.e., first-level REPL. From this level, you can use commands for managing databases and users on the server. You also can open a transaction to a database, which gets you to the second level of REPL.
For a full list of commands on the Server level, see the Server level commands section.
Transaction level
Transaction level is the second level of interaction, i.e., second-level REPL. You can control a transaction and send queries in the transaction.
For a full list of commands on the Transaction level, see the Transaction level reference section.
To send a query, while in Transaction level, type in or insert a TypeQL query and push Enter twice. |
When opening a transaction, you can specify transaction options. For a full list of transaction options, see the Transaction options.
Example
The following example illustrates how to create a database, define a schema, and insert some data into the database.
-
Run Console in the interactive mode and connect it to TypeDB:
typedb console
-
Now, run the following command to create a database:
database create sample_db
-
To define a schema, run the
transaction
command to open aschema
session andwrite
transaction to the database. This command opens a Transaction level REPL. Use it to send the Define query, and commit changes:transaction sample_db schema write define person sub entity; commit
The Transaction level of REPL is announced by the CLI prompt change to include database name, session type, and transaction type.
To send a query in the Transaction level, push Enter twice, as a single push of the Enter is recognized as a line break in the query.
-
Insert data with
data
session andwrite
transaction:transaction sample_db data write insert $p isa person; commit
The above example creates a database with the name sample_db
,
defines a simple schema with the single person
type,
then inserts a single instance of the type into the database.
Non-interactive mode
You can run Console commands using the --command
argument:
typedb console --command=<command1> --command=<command2>
The following example achieves the same results as the one in the interactive mode via the command line arguments. Run the following command in a terminal to start TypeDB and execute queries:
typedb console --command="database create sample_db" \
--command="database list" \
--command="transaction sample_db schema write" \
--command="define person sub entity;" \
--command="commit" \
--command="transaction sample_db data write" \
--command='insert $p isa person;' \
--command="commit"
See the output
+ database create sample_db Database 'sample_db' created + database list sample_db + transaction sample_db schema write ++ define person sub entity; Concepts have been defined ++ commit Transaction changes committed + transaction sample_db data write ++ insert $p isa person; { $p iid 0x826e80017fffffffffffffff isa person; } answers: 1, total (with concept details) duration: 56 ms ++ commit Transaction changes committed
Scripting
You can create a script file that contains the list of commands to run. These are the very same commands that are used in the Interactive mode or Non-interactive mode. For the full list of commands, see the References below.
To use a script file with commands, run Console with the --script
argument and a path to the script file:
typedb console --script=<script-file-path>
Each line in the script file is interpreted as one command, so multiline queries are not available in this mode.
You can overcome this limitation, by calling a TypeQL query from a file with the |
Prepare the script to run and save it to a local file.
For example, let’s try the following script.txt
file:
database create test transaction test schema write define person sub entity, owns name; name sub attribute, value string; commit transaction test data write insert $x isa person, has name "Bob"; commit transaction test data read match $x isa person, has name $f; fetch $f; close database delete test
Execute the script with TypeDB Console:
typedb console --script=PATH/script.txt
Where PATH/script.txt
is the path to the file and the filename.
See the output
+ database create test Database 'test' created + transaction test schema write ++ define person sub entity, owns name; name sub attribute, value string; Concepts have been defined ++ commit Transaction changes committed + transaction test data write ++ insert $x isa person, has name "Bob"; { $_0 Bob isa name; $x iid 0x826e80017fffffffffffffff isa person; } answers: 1, total duration: 15 ms ++ commit Transaction changes committed + transaction test data read ++ match $x isa person, has name $f; fetch $f; { "f": { "value": "Bob", "type": { "label": "name", "root": "attribute", "value_type": "string" } } } answers: 1, total duration: 10 ms ++ close Transaction closed + database delete test Database 'test' deleted
Run a query from a file
To run a TypeQL query stored in a file, use the source <filename>
command.
This command is available from the Transaction level REPL:
transaction sample_db schema write source schema.tql commit
The schema.tql
file should be located in the working directory, when you run TypeDB Console,
and contain a valid Define query.
Script using query files examples
To overcome the limitation of a script file for one command per line, you can store multiple multiline queries in a separate file and run them with the source command.
For example, let’s use the following script file to:
-
Create the
iam_sample_db
database -
Load the IAM schema form the iam-schema.tql file in a schema session
-
Load sample data from the iam-data.tql file in a data session
-
Run a Fetch query
-
Delete the database to reset the environment
database create iam_sample_db transaction iam_sample_db schema write source iam-schema.tql commit transaction iam_sample_db data write source iam-data.tql commit transaction iam_sample_db data read match $p isa person; fetch $p as person: attribute; close database delete iam_sample_db
See the iam-schema.tql
define
credential sub attribute, value string;
full-name sub attribute, value string;
id sub attribute, abstract, value string;
email sub id, value string;
name sub id, value string;
number sub id, value string;
path sub id, value string;
object-type sub attribute, value string;
ownership-type sub attribute, value string;
review-date sub attribute, value datetime;
size-kb sub attribute, value long;
validity sub attribute, value boolean;
access sub relation,
relates action,
relates object,
plays change-request:change,
plays permission:access;
change-request sub relation,
relates change,
relates requestee,
relates requester;
membership sub relation,
relates member,
relates parent;
collection-membership sub membership,
relates collection as parent;
group-membership sub membership,
relates group as parent;
set-membership sub membership,
relates set as parent;
ownership sub relation,
relates owned,
relates owner;
group-ownership sub ownership,
owns ownership-type,
relates group as owned;
object-ownership sub ownership,
owns ownership-type,
relates object as owned;
permission sub relation,
owns review-date,
owns validity,
relates access,
relates subject;
segregation-policy sub relation,
owns name,
relates action,
plays segregation-violation:policy;
violation sub relation,
abstract;
segregation-violation sub violation,
relates object,
relates policy,
relates subject;
action sub entity,
abstract,
owns name,
owns object-type,
plays access:action,
plays membership:member,
plays segregation-policy:action;
operation sub action;
operation-set sub action,
plays set-membership:set;
object sub entity,
abstract,
owns object-type,
plays access:object,
plays membership:member,
plays object-ownership:object,
plays segregation-violation:object;
resource sub object,
abstract;
file sub resource,
owns path,
owns size-kb;
record sub resource,
owns number;
resource-collection sub object,
abstract,
plays collection-membership:collection;
database sub resource-collection,
owns name;
directory sub resource-collection,
owns path,
owns size-kb;
subject sub entity,
abstract,
owns credential,
plays change-request:requestee,
plays change-request:requester,
plays membership:member,
plays ownership:owner,
plays permission:subject,
plays segregation-violation:subject;
user sub subject,
abstract;
person sub user,
owns email,
owns full-name;
user-group sub subject,
abstract,
plays group-membership:group,
plays group-ownership:group;
business-unit sub user-group,
owns name;
user-account sub user-group,
owns email;
user-role sub user-group,
owns name;
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;
};
See the iam-data.tql
# Subjects
insert $p isa person, has full-name "Masako Holley", has email "masako.holley@typedb.com"; # No access
insert $p isa person, has full-name "Pearle Goodman", has email "pearle.goodman@typedb.com"; # Sales manager
insert $p isa person, has full-name "Kevin Morrison", has email "kevin.morrison@typedb.com"; # Full access
# Objects
insert $f isa file, has path "iopvu.java", has size-kb 55;
insert $f isa file, has path "zlckt.ts", has size-kb 143;
insert $f isa file, has path "psukg.java", has size-kb 171;
insert $f isa file, has path "axidw.java", has size-kb 212;
insert $f isa file, has path "lzfkn.java", has size-kb 70;
insert $f isa file, has path "budget_2022-05-01.xlsx", has size-kb 758;
insert $f isa file, has path "zewhb.java";
insert $f isa file, has path "budget_2021-08-01.xlsx", has size-kb 1705;
insert $f isa file, has path "LICENSE";
insert $f isa file, has path "README.md";
# Operations
insert $o isa operation, has name "modify_file";
insert $o isa operation, has name "view_file";
# Potential access types
match $ob isa file, has path "iopvu.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zlckt.ts"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "psukg.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "axidw.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "lzfkn.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2022-05-01.xlsx"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zewhb.java"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2021-08-01.xlsx"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "LICENSE"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "README.md"; $op isa operation, has name "modify_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "iopvu.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zlckt.ts"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "psukg.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "axidw.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "lzfkn.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2022-05-01.xlsx"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "zewhb.java"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "budget_2021-08-01.xlsx"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "LICENSE"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
match $ob isa file, has path "README.md"; $op isa operation, has name "view_file"; insert $a (object: $ob, action: $op) isa access;
# Permissions
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "iopvu.java";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "zlckt.ts";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "psukg.java";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "axidw.java";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "lzfkn.java";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "budget_2022-05-01.xlsx";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "zewhb.java";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "budget_2021-08-01.xlsx";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "LICENSE";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Kevin Morrison"; $o isa object, has path "README.md";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "budget_2022-05-01.xlsx";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "zewhb.java";
$a isa action, has name "view_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "budget_2021-08-01.xlsx";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "LICENSE";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
match $s isa subject, has full-name "Pearle Goodman"; $o isa object, has path "README.md";
$a isa action, has name "modify_file"; $ac (object: $o, action: $a) isa access;
insert $p (subject: $s, access: $ac) isa permission;
Make sure you have the above script file and tql
files saved to the working directory.
Run the script with TypeDB Console using the --script
argument,
as you did before in the script example.
See the output
+ database create iam_sample_db Database 'iam_sample_db' created + transaction iam_sample_db schema write ++ source iam-schema.tql Concepts have been defined ++ commit Transaction changes committed + transaction iam_sample_db data write ++ source iam-data.tql ++ commit Transaction changes committed + transaction iam_sample_db data read ++ match $p isa person; fetch $p as person: attribute; { "person": { "attribute": [ { "value": "kevin.morrison@typedb.com", "type": { "label": "email", "root": "attribute", "value_type": "string" } }, { "value": "Kevin Morrison", "type": { "label": "full-name", "root": "attribute", "value_type": "string" } } ], "type": { "label": "person", "root": "entity" } } } { "person": { "attribute": [ { "value": "masako.holley@typedb.com", "type": { "label": "email", "root": "attribute", "value_type": "string" } }, { "value": "Masako Holley", "type": { "label": "full-name", "root": "attribute", "value_type": "string" } } ], "type": { "label": "person", "root": "entity" } } } { "person": { "attribute": [ { "value": "pearle.goodman@typedb.com", "type": { "label": "email", "root": "attribute", "value_type": "string" } }, { "value": "Pearle Goodman", "type": { "label": "full-name", "root": "attribute", "value_type": "string" } } ], "type": { "label": "person", "root": "entity" } } } answers: 3, total duration: 27 ms ++ close Transaction closed + database delete iam_sample_db Database 'iam_sample_db' deleted
Troubleshooting
Non-ASCII characters
TypeDB can use type and variable labels and store string value attributes that have characters outside the ASCII range, for example, non-English letters, symbols, and emojis. To manipulate them using Console, the Console’s terminal must use a locale with a compatible code set, such as Unicode.
If it doesn’t, these characters will most likely be rendered as ?
symbols in Console.
If this issue occurs, you can use the following fix:
-
Linux
-
macOS
-
Windows
Use locale -a
to list all installed locales, and use export
to set the environment.
For example, to use en_US.UTF-8
run:
bash export LANG=en_US.UTF-8 && export LC_ALL=en_US.UTF-8
Use locale -a
to list all installed locales, and use export
to set the environment.
For example, to use en_US.UTF-8
run:
bash export LANG=en_US.UTF-8 && export LC_ALL=en_US.UTF-8
Use Windows Terminal
or run chcp in the
terminal (e.g., chcp 936
for Chinese text).
Most systems also allow us to set the system-wide locale. However, this impacts the appearance of other applications.
References
Console CLI arguments
The following arguments can be used when you invoke TypeDB Console:
Argument | Alias | Description |
---|---|---|
TypeDB Core specific |
||
|
Address to which Console will connect to: IP address and IP port separated by colon.
Default value: |
|
TypeDB Cloud specific |
||
|
Address to which Console will connect to. |
|
|
Username |
|
|
Enable a password prompt |
|
|
Whether to connect with TLS encryption |
|
|
Path to the TLS root CA file |
|
Common |
||
|
|
Show help message. |
|
Commands to run in the Console, without interactive mode |
|
|
Script with commands to run in the Console, without interactive mode. |
|
|
|
Print version information and exit. |
|
Disable anonymous error reporting. |
Server level commands
Use these commands at the Server level of TypeDB’s REPL:
Command | Description |
---|---|
Database management |
|
|
Create a database with the name |
|
List all databases on the server |
|
Delete a database with the name |
|
Print the schema of the database with the name |
User management |
|
|
List all users on the server |
|
Create a user with the name |
|
Update the password for the current user |
|
Set password for the user with the name |
|
Delete a user with the name |
Open a transaction |
|
|
Start a transaction to the database with the name |
Common |
|
|
Print help menu |
|
Clear console screen |
|
Exit console |
Transaction level commands
Use these commands in the Transaction level of TypeDB Console’s REPL.
The prompt at the Transaction level contains the database name, as well as session and transaction types, for example,
iam::data::read>
.
Command | Description |
---|---|
Querying |
|
|
Type in TypeQL query directly. Push Enter once for a line break in a query. Push Enter twice (once more on a new line) to send a query. |
|
Run TypeQL queries from a file. You can use a relative or absolute path. On Windows escape |
Transaction control |
|
|
Commit the changes and close the transaction. |
|
Rollback the transaction — remove any uncommitted changes, while leaving the transaction open. |
|
Close the transaction without committing changes. |
Common |
|
|
Print help menu. |
|
Clear console screen. |
|
Exit console. |
Transaction options
The following flags can be passed in the transaction
command as transaction options, for example:
transaction sample_db data read --infer true
Option | Allowed values | Description |
---|---|---|
|
|
Enable or disable inference. |
|
|
Enable or disable inference tracing. |
|
|
Enable or disable inference explanations. |
|
|
Enable or disable parallel query execution. |
|
|
Set RPC answer batch size. |
|
|
Enable or disable RPC answer prefetch. |
|
|
Kill idle session timeout (ms). |
|
|
Kill transaction timeout (ms). |
|
|
Acquire exclusive schema session timeout (ms). |
|
|
Allow or disallow reads from any replica |
Version Compatibility
TypeDB Console | Protocol encoding version | TypeDB Core | TypeDB Cloud |
---|---|---|---|
3 |
2.28.0 |
2.28.0 |
|
3 |
2.27.0 |
2.27.0 |
|
3 |
2.26.6 |
2.26.6 |
|
3 |
2.25.7 |
2.25.7 |
|
2 |
2.24.17 |
2.24.17 |
|
1 |
2.18.0 to 2.23.0 |
2.18.0 to 2.23.0 |
|
N/A |
2.17.0 |
2.17.0 |
See older versions
TypeDB Console | Protocol encoding version | TypeDB Core | TypeDB Cloud |
---|---|---|---|
2.16.1 |
N/A |
2.16.1 |
2.16.1 to 2.16.2 |
2.15.0 |
N/A |
2.15.0 |
2.15.0 |
2.14.2 |
N/A |
2.14.2 to 2.14.3 |
2.14.1 |
2.14.0 |
N/A |
2.14.0 to 2.14.1 |
2.14.1 |
2.12.0 |
N/A |
2.12.0 to 2.13.0 |
2.12.0 to 2.13.0 |
2.11.0 |
N/A |
2.11.0 to 2.11.1 |
2.11.1 to 2.11.2 |
2.10.0 |
N/A |
2.10.0 |
2.10.0 |
2.9.0 |
N/A |
2.9.0 |
2.9.0 |
2.8.0 |
N/A |
2.8.0 to 2.8.1 |
2.5.0 |
2.6.1 |
N/A |
2.6.1 to 2.7.1 |
2.5.0 |
2.6.0 |
N/A |
2.6.0 |
2.5.0 |
2.5.0 |
N/A |
2.5.0 |
2.3.0 |
2.4.0 |
N/A |
2.4.0 |
2.3.0 |
2.3.2 |
N/A |
2.3.2 to 2.3.3 |
2.3.0 |
2.3.1 |
N/A |
2.3.1 |
2.3.0 |
2.3.0 |
N/A |
2.3.0 |
2.3.0 |
2.1.3 |
N/A |
2.1.3 to 2.2.0 |
2.1.2 |
2.1.2 |
N/A |
2.1.2 |
2.0.3 |
2.1.1 |
N/A |
2.1.1 |
2.0.3 |
2.1.0 |
N/A |
2.1.0 |
2.0.3 |
2.0.1 |
N/A |
2.0.1 to 2.0.2 |
2.0.1 to 2.0.2 |
2.0.0 |
N/A |
2.0.0 |
2.0.0 |
1.0.8 |
N/A |
1.1.0 to 1.8.4 |
- |