TypeDB Console
Install
If using versions previous to 3.1.0, you will need to install Java 11+. |
If you are using a distribution of TypeDB CE (TypeDB server), you may already have TypeDB Console included and can skip this step!
To verify, just run typedb --help
.
For installation instructions of only the Console distribution, follow the steps below for your OS:
-
macOS
-
Linux
-
Windows
-
Download the latest package for your system architecture: x86_64 / arm64
For other versions, see the Downloads repository page.
-
Extract the archive into a new directory:
$ sudo mkdir /opt/typedb-console $ unzip ~/Downloads/<filename>.zip -d /opt/typedb-console
Where
<filename>
is the name of the archive. -
Add a symlink to the TypeDB Console executable in the
/usr/local/bin
directory:$ ln -s /opt/typedb-console/<filename>/typedb /usr/local/bin/typedb
-
Download the latest package for your system architecture: x86_64 / arm64
For other versions, see the Downloads repository page.
-
Extract the archive into a new directory:
$ mkdir /opt/typedb-console $ tar -xzf ~/Downloads/<filename>.tar.gz -C /opt/typedb-console
Where
<filename>
is the name of the archive. -
Add a symlink to the TypeDB Console executable in the
/usr/local/bin
directory:$ ln -s /opt/typedb-console/<filename>/typedb /usr/local/bin/typedb
-
Download the latest package for your system architecture: x86_64
For other versions, see the Downloads repository page.
-
Extract the archive into a new directory:
$ mkdir "C:\Program Files\TypeDB Console" $ tar xvf "C:\Users\username\Downloads\<filename>.zip" -C "C:\Program Files\TypeDB Console"
Where
<filename>
is the name of the archive. -
Update the
PATH
environment variable:$ setx /M PATH "%path%;C:\Program Files\TypeDB Console\<filename>"
Restart the terminal window for the changes to environment variables to take effect.
Connect to TypeDB
TypeDB Console can connect to TypeDB CE, TypeDB Cloud instances, or TypeDB Enterprise deployments. Running TypeDB Console initiates a network connection to a TypeDB server.
typedb console --address=<server-address> --username=<username>
You will be prompted for a password.
Use --tls-disabled
to connect to a server without encryption.
The default username and password are |
As a result, you get a welcome message from TypeDB Console followed by a command line prompt.
Welcome to TypeDB Console. >>
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. |
As of version 3.1.0, the command to open a transaction differs: The new command, as of version 3.1.0:
Previously, before version 3.1.0:
|
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 --address=<server-address> --username=<username>
-
Now, run the following command to create a database:
database create sample_db
-
To define a schema, run the
transaction
command to open aschema
transaction to the database. This command opens a Transaction level REPL. Use it to send a define query and commit changes:transaction schema sample_db define entity user; commit
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 a
write
transaction:transaction write sample_db insert $u isa user; commit
The above example creates a database with the name sample_db
, defines a simple schema with a single user
type, then inserts a single instance of the type into the database.
Pasting a block of console commands together is also possible, and equivalent to submitting a script to the console at that point. This is particularly useful when document examples with self-contained transaction operations, and schema and data queries.
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 --address=<server-address> --username=<username> \
--command="database create sample_db" \
--command="database list" \
--command="transaction schema sample_db" \
--command="define entity user;" \
--command="commit" \
--command="transaction write sample_db" \
--command='insert $u isa user;' \
--command="commit"
See the output
+ database create sample_db Successfully created database. + database list sample_db + transaction schema sample_db ++ define entity user; Finished schema query. ++ commit Successfully committed transaction. + transaction write sample_db ++ insert $u isa user; Finished write query validation and compilation... Finished writes. Streaming rows... -------- $u | isa user, iid 0x1e00000000000000000000 -------- Finished. Total answers: 1 ++ commit Successfully committed transaction.
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>
By convention, console scripts, which can manipulate transactions and server state, use the .tqls
extension.
In contrast, files containing only TypeQL queries normally use the .tql
extension.
Scripts use the exact same format as the interactive REPL. This means queries in the script must be terminated with an empty newline. |
Prepare the script to run and save it to a local file.
For example, let’s try the following script.tqls
file:
database create test transaction schema test define entity user owns name; attribute name value string; commit transaction write test insert $u isa user, has name "Bob"; commit transaction read test match $u isa user, has name $n; select $n; close database delete test
Execute the script with TypeDB Console non-interactively:
typedb console --username=<username> --password=<password> --script=<PATH/script.tqls>
Where <PATH/script.tqls>
is the path to the file and the filename.
See the output
+ database create test Successfully created database. + transaction schema test ++ define entity user owns name; attribute name value string; Finished schema query. ++ commit Successfully committed transaction. + transaction write test ++ insert $u isa user, has name "Bob"; Finished write query validation and compilation... Finished writes. Streaming rows... -------- $u | isa user, iid 0x1e00000000000000000000 -------- Finished. Total answers: 1 ++ commit Successfully committed transaction. + transaction read test ++ match $u isa user, has name $n; select $n; Finished read query validation and compilation... Streaming rows... -------- $n | isa name "Bob" -------- Finished. Total answers: 1 ++ close Transaction closed + database delete test Successfully deleted database.
Run query(ies) from a file
To run a series of TypeQL queries stored in a file from within a REPL, use the source <filename>
command.
Each query should be separated with an empty newline.
Note that this means long queries cannot be split over multiple lines containing empty lines.
Use comments instead.
This command is available from the Transaction level REPL:
transaction schema sample_db source schema.tql commit
The schema.tql
file should be located in the working directory or be an absolute path.
Combining scripts and query files
Let’s use a script file to:
-
Create the
sample_db
database -
Load the schema form the schema.tql file in a schema transaction
-
Load sample data from the data.tql file in a write transaction
-
Run a match-fetch query
-
Delete the database to reset the environment
database create sample_db transaction schema sample_db source schema.tql commit transaction write sample_db source data.tql commit transaction read sample_db match $u isa user; fetch { "user": { $u.* } }; close database delete sample_db
See the schema.tql
define
entity content @abstract,
owns id @key;
entity page @abstract, sub content,
owns page-id,
owns name,
owns bio,
owns profile-picture,
plays posting:page,
plays following:page;
entity profile @abstract, sub page,
owns username,
owns name @card(0..3),
plays group-membership:member,
plays location:located,
plays content-engagement:author,
plays following:follower;
entity user sub profile,
owns email,
owns phone @regex("^\d{8,15}$") @unique,
owns karma,
owns relationship-status,
plays friendship:friend,
plays family:relative,
plays relationship:partner,
plays marriage:spouse,
plays employment:employee;
relation social-relation @abstract,
relates related @card(0..);
relation friendship sub social-relation,
relates friend as related @card(0..);
relation family sub social-relation,
relates relative as related @card(0..1000);
relation relationship sub social-relation,
relates partner as related,
owns start-date;
relation marriage sub relationship,
relates spouse as partner,
owns exact-date,
plays location:located;
entity organisation sub profile,
owns tag @card(0..100),
plays employment:employer;
entity company sub organisation;
entity charity sub organisation;
relation employment,
relates employer,
relates employee,
owns start-date,
owns end-date;
entity group sub page,
owns group-id,
owns tag @card(0..100),
plays group-membership:group;
relation group-membership,
relates group,
relates member,
owns start-timestamp,
owns end-timestamp;
entity post @abstract, sub content,
owns post-id,
owns post-text,
owns creation-timestamp @range(1970-01-01T00:00:00..),
owns tag @card(0..10),
plays posting:post,
plays commenting:parent,
plays reaction:parent,
plays location:located;
entity text-post sub post;
entity image-post sub post,
owns post-image;
entity comment sub content,
owns comment-id,
owns comment-text,
owns creation-timestamp,
owns tag @card(0..5),
plays commenting:comment,
plays commenting:parent,
plays reaction:parent;
relation interaction @abstract,
relates subject @abstract,
relates content;
relation content-engagement @abstract, sub interaction,
relates author as subject;
relation posting sub content-engagement,
relates page as content,
relates post @card(0..1000);
relation commenting sub content-engagement,
relates parent as content,
relates comment;
relation reaction sub content-engagement,
relates parent as content,
owns emoji @values("like", "love", "funny", "surprise", "sad", "angry"),
owns creation-timestamp;
relation following,
relates follower,
relates page;
entity place,
owns place-id,
owns name,
plays location:place;
entity country sub place,
plays city-location:parent;
entity city sub place,
plays city-location:city;
relation location,
relates place,
relates located;
relation city-location sub location,
relates parent as place,
relates city as located;
# attributes
attribute id @abstract, value string;
attribute page-id @abstract, sub id;
attribute username sub page-id;
attribute group-id sub page-id;
attribute post-id sub id;
attribute comment-id sub id;
attribute place-id sub id;
attribute name value string;
attribute email value string @regex("^.*@\w+\.\w+$");
attribute phone value string;
attribute karma value double;
attribute relationship-status value string @values("single", "married", "other");
attribute latitude value double;
attribute longitude value double;
attribute event-date @abstract, value datetime;
attribute start-date sub event-date;
attribute end-date sub event-date;
attribute exact-date @abstract, sub event-date;
attribute payload @abstract, value string;
attribute text-payload @abstract, sub payload;
attribute image-payload @abstract, sub payload;
attribute bio sub text-payload;
attribute comment-text sub text-payload;
attribute post-text sub text-payload;
attribute post-image sub image-payload;
attribute profile-picture sub image-payload;
attribute tag value string;
attribute emoji value string;
attribute creation-timestamp value datetime;
attribute start-timestamp value datetime;
attribute end-timestamp value datetime;
# functions
fun all_relatives($user: user) -> { user }:
match
$relative isa user;
{
family (relative: $user, relative: $relative);
} or {
let $intermediate in all_relatives($user);
family (relative: $intermediate, relative: $relative);
};
return { $relative };
See the data.tql
insert
$u1 isa user,
has username "masako-holley",
has phone "185800100011",
has email "masako.holley@typedb.com";
$u2 isa user,
has username "pearle-goodman",
has phone "171255522222",
has email "pearle.goodman@typedb.com";
$u3 isa user,
has username "kevin-morrison",
has phone "110000000",
has email "kevin.morrison@typedb.com";
$relatives1 isa family (relative: $u1, relative: $u2);
$relatives2 isa family (relative: $u2, relative: $u3);
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 sample_db Successfully created database. + transaction schema sample_db ++ source schema.tql Successfully executed 1 queries. ++ commit Successfully committed transaction. + transaction write sample_db ++ source data.tql Successfully executed 1 queries. ++ commit Successfully committed transaction. + transaction read sample_db ++ match $u isa user; fetch { "user": { $u.* } }; Finished read query validation and compilation... Streaming documents... { "user": { "username": "masako-holley", "email": "masako.holley@typedb.com", "phone": "185800100011" } } { "user": { "email": "pearle.goodman@typedb.com", "username": "pearle-goodman", "phone": "171255522222" } } { "user": { "phone": "110000000", "username": "kevin-morrison", "email": "kevin.morrison@typedb.com" } } Finished. Total answers: 3 ++ close Transaction closed + database delete sample_db
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 invoking TypeDB Console:
Argument |
Alias |
Description |
|
Address to which Console will connect to: IP address and IP port separated by colon.
Note that by default, TLS is enabled, which will require an |
|
|
|
Show help message. |
|
Username. |
|
|
Explicitly pass in the password (not recommended). Interactive sessions should let the console safely request for the password. |
|
|
Disable TLS connections. For TypeDB Cloud deployments, there is no reason to use this setting as they can only operate with network TLS encryption. Typically used for development or local work. When using this option, username/password will be sent over the network in plaintext. |
|
|
Path to the TLS root CA file, when the server is using self-managed certificates. |
|
|
Commands to run in the Console, without interactive mode. Repeated invocations will be run in the order provided. |
|
|
Script with commands to run in the Console, without interactive mode. Repeated invocations will be run in order provided Repeated invocations will be run in the order provided. |
|
|
|
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 |
User management |
|
|
Create a user with the name |
|
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 and the transaction type, for example,
sample_db::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. |
Navigation
TypeDB console has several commonly-used REPl features:
-
Use the UP and DOWN arrows to navigate the current REPL’s history - server and transaction histories are retained separately
-
Type in a search prefix, then use UP and DOWN arrows to search the history for previous commands that share the written prefix
-
Use ctrl+r to search through history for a specific term or phrase
Version Compatibility
For older TypeDB versions, you’ll need a compatible version of TypeDB Console. Select the correct TypeDB Console version from the version compatibility table, and download it from Cloudsmith.
Version compatibility table
TypeDB Console | TypeDB | TypeDB Community Edition |
---|---|---|
3.0.0+ |
3.0.0+ |
2.x and 3.x versions are not compatible. |