Write Queries
On the Write Queries page, you can write and run custom queries with GSQL.
You can also import pre-written graph data science algorithms from the TigerGraph Graph Data Science Library to use with your own data set.
The Write Query page is horizontally divided into two parts:
-
Query Editing Panel
-
Result, Log and Visualization Panel
Query Editing Panel
The Query Editing panel is divided into two sub-panels, one for selecting a query and the other for displaying the query for editing. The Query Editor features syntax highlighting customized for the GSQL language and also performs real-time semantic checking.
Above the query editing pane is a toolbar with the following buttons, from left to right:
-
Expand/Collapse: Expand or collapse the Query Editing panel to or from full page mode. The icon changes depending on whether the panel is currently expanded or collapsed.
-
Save: Save the current query draft.
-
Save as: Save the current query as a new query under a new name.
-
Install: Install the query into the database.
-
Run: Run the query. If the query is not installed, the query will run in interpreted mode. Note there is a performance penalty for running queries in interpreted mode.
-
Run Configuration: Set the query runtime configurations.
-
-
Delete: Delete the selected query and its draft.
-
Show query endpoint: Show the RESTful endpoint for executing the query. Only installed queries have endpoints.
-
Download: Download the query as a GSQL file.
-
Discard query draft: Delete the selected query draft.
Create a query or add a query from the algorithm library
To create a new query from scratch, simply click on the "New GSQL Query" button in the bottom-right corner of the left sub-panel, and type in the name of the new query in the pop-up window.
By clicking Choose from library, you can import one or more of the pre-written TigerGraph Graph Data Science Library algorithms to perform common graph data science tasks on your data such as pathfinding, community detection, classification, and more.
If you import the same query from the library more than once, installation will fail. |
A query draft will be created with a template:
To edit an existing query, click on the query name in the list in the left panel.
Save Query Draft
Click the "Save" buttonin the toolbar to save changes as a draft. A query draft is saved as is, regardless of syntax or semantic errors. Draft queries are not installed.
Save as
Click the "Save as" button to save the current query as a new query under a different name. After saving a query as another query, you will be redirected to the new query, and the original current will return to its last saved state.
Run Query in Interpreted Mode
You can run a query in interpreted mode if you have saved it as a draft without errors. Click the "Run" button . Together with the query execution result, a warning message will appear to notify you of the performance concerns of running queries in interpreted mode. To speed up the query performance after you are satisfied with the query, follow the instructions in the next section to install the query.
Run Query
To run the query, click on the "Run" button in the toolbar. If the query has no parameters for you to set, it will run immediately and the result will be shown in the Result panel.
If the query does have input parameters, then the "Enter query parameters" pane will open on the left side of the query editing sub-panel. If there are several parameters, you may need to scroll down to see them all. After entering in all the values you wish to use, click the Run query button at the bottom of the pane.
The query will be executed, and the results will be shown in the Result Panel.
Run Configuration
You can set runtime configurations of the GSQL query by clicking the small downward-pointing arrow button to the right of the Run Query button. A menu will appear with the Run Configuration button; click this button.
This opens the Run Configuration panel, where you can set the GSQL query timeout.
By default, it uses the timeout specified with the RESTPP.Factory.DefaultQueryTimeoutSec
server parameter, which is 16 seconds.
See the TigerGraph Server Command Glossary for more information.
Delete Query
Choose the query you want to delete and click on the "delete" button . The query will be deleted permanently.
Show Query Endpoint
After finishing writing the GSQL queries and installing the queries, you can access the queries via REST endpoints.
By clicking the "Show query endpoint" button , you can see the format of the endpoint to access this query, so that you can integrate the query with your applications.
Download
You can download the selected query by clicking or download all your queries as a tar file by clicking
Delete query draft
You can delete your query draft by clicking the delete button at the end of the icon list:
Install All Queries
If you want to install all queries that you haven’t installed yet, click the "Install all queries" button in the GSQL Queries toolbar.
This is useful if you have imported several queries from the Graph Data Science library and want to install them all at once before running them.
A pop-up window listing all queries to be installed appears:
Click the INSTALL button. Installation may take several minutes depending on the number of queries to install.
Result Panel
The Result panel shows the result of the last run query. Each query generates up to three types of result: visualized graph, JSON text, or log messages. On the left is a toolbar with buttons for changing the the panel size or for switching to a different type of result. The buttons, from top to bottom, are the following:
Menu option | Functionality |
---|---|
Expand/Collapse: Expand or collapse the Result panel. |
|
View schema: Show the graph schema. |
|
Visualize graph result: Display query result in visualized graph. |
|
View JSON result: Display query result in JSON format. |
|
View table result: Display query result in a table. |
|
View logs: Show the log for the most recent query run. |
View schema
Viewing the graph schema makes it more convenient for developers to refer to the schema topology logic and easier to write correct GSQL queries.
Visualize graph result
If the query execution result contains a graph structure, the result will be visualized in this panel as a graph. The panel is the same as the Explore Graph panel. The only difference is that each time you run a query, the previous result will be erased. In Explore Graph the results are added incrementally.
Switch to the JSON Result panel to see the result in JSON format.
View JSON result
If there is no graph structure in the result, the result will be displayed in this panel as a JSON object.
View table result
You can display the query result as a table:
Table rows can be sorted by any column with primitive type values. You can also download the table as a CSV file by clicking the download button next to the table name.
View logs
If a query ran successfully, the Query Log will show a success message. If there was anything wrong when executing your query, such as invalid parameters or runtime errors, an error message will be shown in the Query Log panel:
Expand Panels
If you just want to focus on developing your query, or want to have more space to view your results, click the Expand button in either the Query Editing panel or the Result panel.
If you expand the Query Editing panel, it looks like this:
If you expand the Result panel, it looks like this:
When the panel is expanded, the Expand button becomes the Collapse button . Clicking it will return the display to the split panel view.