Write Queries

On the Write Queries page, you can write and run custom queries with GSQL.

write queries overview 3.3

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 select 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:

write queries toolbar 3.3
  • 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, it will run the query in interpreted mode. Note there is performance penalty to run 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 to execute the query. Only installed queries can see their RESTFul endpoints.

  • Download: Download the query as a gsql file.

  • Discard query draft: Delete the selected query draft.

Add Or Edit Query

To create a new query, simply click on the "New GSQL Query" button upload file btn in the bottom-right corner of the left sub-panel, and type in the name of the new query in the popup window:

create new query 3.6

A query draft will be created with a template:

write queries query draft 3.3

To edit an existing query, click on the query name in the list in the left panel.

Save Query Draft

Click the "save" buttonsave btnin the toolbar to save changes as a draft. This is separate from installing a query.

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.

Graph Data Science Library Queries

GraphStudio is connected to the Graph Data Science Library and can import machine learning algorithms directly from a curated library. Click Choose Query on the Add New Query window to see the query choices. Select any queries that you would like to install. After installation, they will appear in the GSQL Queries window just like user-generated queries.

If you use the Data Science Library to install a query that is already installed, installation will fail.

Run Query in Interpreted Mode

You can run a query in interpreted mode if you have saved it without errors. Click the run query button start loading button. Together with the query execution result, a warning message will appear to notify user of the performance concerns running the query in interpreted mode. To speed up the query performance after you are satisfied with the GSQL query developed in interpreted mode, you can follow the instructions in the next section "Install Query".

Install Query

Saving a query enables the "install query" button publish btn. Click it to install the query, a process which will take about a minute.

install query progress

Run Query

To run the query, click on the "run" button image in the toolbar. If the query has no parameters, it will run directly and the result will be shown in the Result panel.

image

If the query requires parameters, the Enter Query Parameters panel will appear. Enter your parameter values and then click Run query at the bottom of the panel. You may need to scroll the panel to the bottom to find the Run Query button.

The query will be executed, and the results will be shown in the Result Panel.

image

Run Configuration

You can set runtime configurations of the GSQL query by clicking the small image button to the right of the Run Query button, then a drop-down menu will appear with the Run Configuration button.

image

This opens the Run Configuration panel, where you can set the GSQL query timeout. By default, it uses the timeout specified with gadmin server commands in the TigerGraph configuration.

Delete Query

Choose the query you want to delete and click on the "delete" button image. 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 image , you can see the format of the endpoint to access this query, so that you can integrate the query with your applications.

image

Download

You can download the selected query by clicking image or download all your queries as a tar file by clicking image

Delete query draft

You can delete your query draft by clicking image .

Install All Queries

If you want to install all queries that you haven’t installed yet, click the "Install all queries" button image in the GSQL Queries toolbar.

After some verification time, a pop up window listing all queries to be installed will show:

image

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

image

Expand/Collapse: Expand or collapse the Result panel.

image

View schema: Show the graph schema.

image

Visualize graph result: Display query result in visualized graph.

image

View JSON result: Display query result in JSON format.

image

View table result: Display query result in a table.

image

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.

image

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.

image

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.

image

View table result

You can display the query result as a table:

table view

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:

image

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 image in either the Query Editing panel or the Result panel.

If you expand the Query Editing panel, it looks like this:

image

If you expand the Result panel, it looks like this:

image

When the panel is expanded, the Expand button becomes the Collapse button image. Clicking it will return the display to the split panel view.