TypeDB Studio
TypeDB Studio is an IDE specifically designed for TypeDB databases and TypeDB’s query language — TypeQL.
It has unique set of functions and abilities to help with development using TypeDB:
-
Friendly GUI to design schemas and queries for TypeDB databases.
-
Syntax highlighting for TypeQL.
-
Connection to TypeDB servers, including handling transactions.
-
Type Browser for exploring types in a TypeDB database.
-
Query execution, including schema and data, read and write transactions.
-
Local query validation with constraints of an actual database schema before sending the query to server.
-
Graph visualization for query responses.
Installation
Requirements
TypeDB Studio do not require any additional packages to be installed prior the installation, but it needs a TypeDB server to perform most it’s functions. We can use either remote or local TypeDB server.
|
The default TypeDB settings are to run server listening for |
|
We recommend using the latest version of TypeDB server and a compatible version of TypeDB Studio. |
Download & install
Download TypeDB distributive/package for any popular OS family from the Download page.
Follow proper installation procedure of the OS in use.
|
Make sure to grant access for installation wizard to install TypeDB Studio in case any security prompts will appear. |
|
For macOS TypeDB Studio can be installed via homebrew (not recommended for |
Prepare for work
Right after starting TypeDB Studio we can see its main window as it is shown below.
The main panels of the GUI are marked with the following numbers on the image above:
-
Projects panel
-
Type browser
-
Text editor tab
-
Toolbar
To use most of TypeDB Studio functions we need to connect to a TypeDB server and choose a project directory.
Connect to TypeDB server
At the top right-hand corner click the Connect to TypeDB button. It will open a windows with the same name and the connection settings as shown below.
Fill in the address of the TypeDB server. By default, it’s: localhost:1729. Click the Connect button.
Once TypeDB Studio connected to a TypeDB server successfully, the connection manager window should close automatically. If we reopen the window we can find the green status field in the bottom left corner, as shown above.
|
When Studio connected to a TypeDB server it will display the server address in the top right corner instead of the
label of the |
Disconnect from TypeDB server
At the top right-hand corner click the button with the server address in it.
In the Connect to TypeDB window click on the Disconnect button.
Create a database
To create a new database make sure TypeDB Studio is connected to a TypeDB server and click on the Manage Databases button (with a database icon) as shown below.
Enter the name for the new database at the text field at the bottom of the Manage Databases window and hit
Create.
Our database appeared at the list of databases. Now we can close the Manage Databases window by clicking the
Close button.
Select active database
TypeDB Studio lets us work with one database at a time. Thus, to perform any query we need to choose a database first.
We can select it by clicking the dropdown menu at the Toolbar titled database (none) or with a name of previously selected database. It is the only dropdown menu in the Toolbar and is located immediately right of the databases icon.
|
If the dropdown menu isn’t active it usually means that we didn’t connect to a server yet. |
After selecting the database to work with from a list, we will see it’s name on the dropdown list and types hierarchy of the selected database in the Type browser (bottom left of the screen).
Open a project directory
TypeDB Studio stores queries we save on a local machine in a project directory, so we don’t need to rewrite all queries each time we open Studio. To select a project directory click on the open folder icon left of the database icon or click on the Open Project button in the Projects panel on the left (under the database icon).
|
If the Projects panel is not displayed — click the Projects vertical tab on the left edge of the TypeDB Studio window. |
Basic operations
File operations
Create a new file
To create a new file use the button with the plus (+) icon. It is located at the top of the Text editor panel
under the Toolbar. It’s horizontal position adjusted for the number of tabs opened in the Text editor — the
button with plus icon will always stay at the right end of the tabs of the Text editor.
Upon clicking on the plus button a new tab will be opened with the default filename. For new files by default
filename consists of Untitled word, followed by a number, starting from 1 and a file extension of .tql.
This file will be stored at the hidden folder in the current project directory until it will be saved with some other name and path.
Open an existing file
We can open any existing file in the current project directory by double-clicking on the file in the Projects panel. It will create a new tab in the Text editor panel with the contents of the file.
If there is already a tab with the file opened it will become active instead of creating a new one.
Save a file
Any file edited in the Text editor panel is auto saved with a small delay. That includes new files that wasn’t assigned a specific name yet. Those are saved into the hidden folder with their default names. That way if we close TypeDB Studio the all files will be persisted and upon starting the Studio again all files in the hidden folder will be opened automatically.
Upon manual save those Untitled files will be saved with the specified filename and path and deleted from the hidden folder.
To save file manually use the Save Current File (floppy disk đź’ľ icon) button at the left end of the Toolbar.
Query design
One of the most important functions of TypeDB Studio is to provide an environment to design and debug queries to TypeDB databases. For that we have the Text editor panel with TypeQL syntax highlighting and the Toolbar with transaction controls.
Text editor panel
Text editor panel doesn’t have a visible title, but it’s the biggest area in the middle of the TypeDB Studio
that is being used to work with text information. It does have tabs at the top to switch between different opened files.
The currently selected file’s content displayed in the main section with line numbers at the left edge of the Text editor panel.
All text in the Text editor panel will be displayed with TypeQL syntax highlighting.
In the bottom right corner of TypeDB Studio window there is an indicator for cursor location that contains the line number and current symbol position in that line.
The following functions can be activated from the context menu available by right-clicking inside the Text editor main section:
-
Copy/Cut/Paste
-
Find/Replace
-
Run File/Run Selection
-
Increase/Decrease/Reset Text Size
Query execution
To run a query that we have prepared in a tab of the Text editor panel, use the transaction controls in the top Toolbar.
How to run a query
Make sure TypeDB Studio is connected to a TypeDB server, database is selected and project directory is opened.
-
Make sure the query to run is open in the active tab of the text-editor panel.
If it’s not the case: write a new one or open an existing file with query to run.
-
Choose the correct session (
schema/data) type and transaction (read/write) type to run the query by clicking on those options on the Toolbar switches. -
Run the query by clicking on the Run Query (â–¶) button.
Run panel will be expanded on the bottom of the query to show the results of the query execution attempt.
-
If it’s the
writetransaction type — wait for transaction control options to be ready and commit or close the transaction (by clicking on the Commit transaction (âś”) or Close transaction (x) buttons respectively).
The result of the query is displayed in the Run panel under the Text editor.
If any error occurs during the query validation or transaction it is shown as red popup in the bottom right corner of the TypeDB Studio window. Additional information about the error is displayed in the results of the query in the Run panel.
If a write transaction committed successfully — a blue pop-up with a transaction confirmation is displayed.
See example below.
For more information on different control elements for query execution, see the Transaction controls section below.
How to see results
Under the Text editor panel there is the Run panel, but it is collapsed by default if no query has been run yet.
To expand it perform any query or just click on the upwards-pointing chevron in the bottom right corner of TypeDB Studio window, above the cursor location indicator.
Run panel has 2 sets tabs:
-
Tabs at the top of the Run panel are for different query attempts.
By default, every query sent will overwrite the existing tab, but if we enable the pin icon at the beginning of the tab name by clicking it — the tab will become pinned and stay. A new tab will appear on the right from the last pinned one upon next query execution.
-
Tabs at the bottom of the Run panel are for different results for the currently selected query attempt (tab at the top of the Run panel). These include the
Logtab with direct textual Studio output and theGraphtabs (one per every query statement in the Text editor panel) with graph visualization of response.
Use Log tab to see textual output from the query execution (including error and query execution messages)
Transaction controls
To control query execution we have the top Toolbar elements located to the right from the database selection drop-down menu. See below.
From left to right (numbered respectively to the screenshot numbers):
-
Session type switch:
-
schema— to use schema session type -
data— to use data session type
-
-
Transaction type switch:
-
write— to use write transaction -
read— to use read transaction
-
-
snapshot button — enables snapshot feature that encapsulates transaction in a snapshot of a database’s data until the transaction committed or closed. Write transactions are always snapshoted. May be enabled or disabled for read transactions.
-
infer button — enable inferring data by rules. Only available for read transactions.
-
explain button — enable explanations mechanics by providing
explainablesmethods for results. Only available for read transactions with snapshot and infer enabled. -
Transaction status (Circle (â—Ź) icon) indicator — transaction activity indicator. Green if there is a transaction opened by TypeDB Studio at this moment. Gray if there is no opened transaction. Rotating animation — TypeDB Studio processing the query or the results (including additional API calls).
-
Close transaction (x icon) button — close active transaction without committing the results.
-
Rollback transaction (U-turn (⟲) icon) button — revert the transaction results without closing it.
-
Commit transaction (Tick (âś”) icon) button — commit the changes and close the transaction.
-
Run Query (play (â–¶) icon) button — run query or queries in the active tab of the Text editor panel. It will open a transaction (with the session type and transaction type specified in the Toolbar on the left) and execute the TypeQL code against the selected database.
-
Stop Signal (lighting (⚡) icon) button — stop query execution after the next result.
Inference
To run a query with inference, simply switch the inference option on before executing a query.
The inference transaction option can be switched on and off with the infer button in the top Toolbar.
|
If the infer button is inactive, double-check the following prerequisites are met:
|
As a result of running a query with inference we can get results in the Run panel. If there are any inferred instances of data they will be shown with green lining in the graph visualization. And inferred connections (ownerships or roles played) will be shown as green arrows. See the example below.
Explanation
To run a query with explanation, simply switch the explanation option on before executing a query. To be able to do that the inference and the snapshot options must also be enabled.
The explanation transaction option can be switched on and off with the explain button in the top Toolbar. The inference and snapshot options can be enabled by the infer and the snapshot buttons respectively.
|
If the explain button is inactive, double-check the following:
|
As a result of running a query with inference and explanation options we can get results in the Run panel. If there are any inferred instances of data they will be shown with green lining in the graph visualization. And inferred connections (ownerships or roles played) will be shown as green arrows. As it was shown in the inference example above.
The only difference is — double-clicking on any explainable inferred results will spawn an explanation. An explanation is a set of additional instances and connections, that provide a direct explanation of the selected explainable inferred result. See the example below.
Type browser capabilities
Under the Projects panel that shows the project directory TypeDB has Type Browser panel that shows all types of the schema of the current database.
|
If the Type Browser panel is not displayed — click the Type Browser vertical tab on the left edge of the TypeDB Studio window. |
All types are divided in three top level built-in types:
-
Attribute
-
Entity
-
Relation
In an empty database (without a schema) only these three built-in types shown in the panel.
In a database with a schema all types displayed in the exact hierarchy they were created (subtypes inside their supertypes). We can easily collapse or expand all the types in the structure tree by clicking the associated buttons on the top of the Type Browser panel with double chevrons (arrow heads) pointing down or up respectively.
Double-clicking on any type will open the Type editor with information about the selected type in a tab of the Text editor.
Type Browser panel can be closed by clicking the X icon in the top right corner of the panel. To reopen the panel click the Type Browser tab on the left edge of the TypeDB Studio window.
Export schema
We can export schema of the database by clicking the Export Schema Types button (second in row from left to right) on the top of the Type Browser panel. It creates a new tab with inserted TypeQL code that creates the exact schema that is in the current database.
|
The Export Schema Types button doesn’t include rules into its output. That will be fixed in some of the next versions of the TypeDB Studio. |
Type editor
By double-clicking any type we can open the type editor window that shows all information about the selected type and allows us to easily edit the type.
We can rename the type, change its supertype, abstract property, see all the connected types (subtypes, owned attributes or owners of this particular attribute, related and played roles).
By clicking on one of the connected types we can see all information about it as well.
Rename a type
|
For the renaming functions to be active set the session type switch to the |
In TypeDB Studio we can rename a type in two ways:
-
Open the type editor window by double-clicking on the type. At the very top click on the pencil icon immediately right from the type name. Edit the name in the Label field and press Rename button to finalize.
-
Right-click on the type in the Type browser list. Click on the Rename Type option. Edit the name in the Label field and press Rename button to finalize.
|
Renaming a type in any of this two ways will update the relevant type references in the schema and will not lead to loosing existing data. All existing instances of the type will be available under the new types name. |
Delete a type
|
For the deleting functions to be active set the session type switch to the |
In TypeDB Studio we can delete a type in two ways:
-
Open the type editor window by double-clicking on the type. At the very bottom click on the Delete button and press Confirm button. Commit the transaction with the green tick at the top of the Studio window.
-
Right-click on the type in the Type browser list. Click on the Delete option and press Confirm button. Commit the transaction with the green tick at the top of the Studio window.
|
In some cases the Delete option and button can be disabled. That means there are some conditions that prevent us from deleting this type. For example, we can’t delete a type that has a subtype. |
Settings
To configure TypeDB Studio open the Manage Preferences window by clicking on the button with the gear (âš™) icon in the top right corner of the TypeDB Studio window.
TypeDB Studio has the following settings available:
-
Graph Visualiser
-
Enable Graph Output — Turns on visualization of query results as graphs on a separate tab of the Run panel.
Default value: On.
-
-
Project Manager
-
Set Ignored Paths — All paths mentioned here will be invisible in any Project directory opened in Studio.
Default value:.git.
-
-
Query Runner
-
Default Get Query Limit — Limits the maximum number of results to be returned from a get query to a database if no limit explicitly stated in the query.
Default value: 1000.
-
-
Text Editor
-
Enable Autosave — Enables autosave function for files opened in TypeDB Studio.
Default value: On.
-