Querying Choices

TigerGraph provides several ways to write and run queries, allowing you to choose the approach that best fits your needs and workflow.

These choices represent different dimensions of querying, such as the language you use, how queries are structured, how they are executed, and how they run across a cluster.

This page summarizes these choices in six areas:

Query Languages

Query Language Options:

GSQL

GSQL is TigerGraph’s original native language.

It supports graph traversal and pattern-matching queries using declarative syntax similar to SQL. It also extends SQL-style queries with procedural programming capabilities, enabling more advanced algorithmic queries. GSQL includes accumulators for efficient analytics and allows queries to be installed (precompiled) to optimize execution performance.

GSQL is used not only for querying and schema definition, but also for data loading. The data loading language lets you define stored procedures (jobs) that map and transform tabular data into graph structures.

OpenCypher

openCypher is a popular open-source declarative query language for property graphs. It is well suited for basic graph traversal queries and pattern matching queries. More about openCypher can be found at openCypher.org.

GSQL V3 Syatax supports the majority of openCypher features, embedded within its native GSQL framework. To learn to how to run OpenCypher on TigerGraph, see the OpenCypher in GSQL tutorial.

GQL

GQL is a new ISO standard for a property graph query language. Its initial version was published in 2024, focusing on pattern matching queries. TigerGraph was and is a contributing member of the ISO GQL committee.

GQL borrows from and extends both OpenCypher and GSQL, enabling a graceful transition for users. GSQL’s V3 Syntax for path patterns aligns with GQL’s syntax. GQL can work with both schema-first and schema-optional graph databases.

TigerGraph currently supports the path pattern matching syntax (the MATCH or FROM clause) of GQL.

  • Use GSQL for analytical and algorithmic queries.

  • Use OpenCypher for graph traversal queries if you are already familar with it.

  • Become familiar with V3 syntax to learn GQL.

Query Structure

Query Structure Options:

  • Stored Procedure (procedural and saved)

  • Anonymous (procedural and ad hoc)

  • Non-Procedural (ad hoc)

Stored Procedure Queries

A stored procedure is a named sequence of executable statements that is saved, and then executing by calling it by name.

Key characteristics:

  • Supports loops and conditional flow to implement algorithms and analytics

  • Accepts input parameters

  • Has a header and body (bounded by curly braces)

  • Output is explicitly specified with PRINT statements

Example of a Stored Procedure Query
CREATE QUERY topMovies(INT year, INT k) {

topK = SELECT m FROM (m:Movie) WHERE m.year == year
       ORDER BY m.boxoffice DESC
       LIMIT k;
PRINT topK;
}

Anonymous Queries

Sometimes you want to run a query only once or a few times. Instead of saving it first and then calling it, you can run it immediately.

Anonymous queries are similar to stored procedure queries except:

  • They do not have a name

  • They do not accept parameters

  • They still have a header and body

  • Output is produced using PRINT

Example of an Anonymous Query
INTERPRET QUERY () {

topK = SELECT m FROM (m:Movie) WHERE m.year == 1939
       ORDER BY m.boxoffice DESC
       LIMIT 10;
PRINT topK;
}

Non-Procedural Queries

Introduced in 4.2, non-procedural queries allow you to run single-statement queries directly.

  • No header

  • Output is automatic

  • Single query statements do not need body delimiters

  • You can optionally use BEGIN and END for multi-line queries

Example of an Non-Procedural Query
SELECT m FROM (m:Movie) WHERE m.year == 1939 ORDER BY m.boxoffice DESC LIMIT 10

Stored procedural queries that are installed before running generally execute faster and more efficiently.

Query APIs

There are four major APIs for running queries and performing other database operations:

Table 1. Query APIs
API Description Use Cases

GSQL CLI

Classic SQL-like commands

text-based, interactive user

REST endpoints

HTTP requests, JSON responses

General application development

GraphStudio, Savanna

Browser GUI-based interaces for building graphs, developing queries, and running queries

Cloud users, those who prefer a graphical interface

pyTigerGraph

Open-source Python library

Data science applications based on Python

When your application builds queries dynamically, the REST API or pyTigerGraph library is often the best fit.

Execution Mode

Execution mode determines whether TigerGraph installs a query before running it.

Execution Mode Options:

  • INSTALL + RUN

  • INTERPRET

INSTALL + RUN

TigerGraph installs (compiles and optimizes) the query before execution.

This provides the best performance and is recommended for production workloads.

Install and run a stored procedure query

The most performant way to run a GSQL query is to create it, install it, and run it.

During installation, TigerGraph performs optimizations that are not available in interpreted mode.

CREATE QUERY topMovies(INT year, INT k) {

topK = SELECT m FROM (m:Movie) WHERE m.year == year
       ORDER BY m.boxoffice DESC
       LIMIT k;
PRINT topK;
}
INSTALL QUERY topMovies
RUN QUERY topMovies(1939, 10)

INTERPRET

TigerGraph runs the query immediately without installation.

This mode is useful for development, testing, and exploratory queries.

Interpret a stored procedure query

When developing a query, you may want to test changes quickly without reinstalling it each time.

In this case, skip INSTALL and use INTERPRET.

CREATE QUERY topMovies(INT year, INT k) {

topK = SELECT m FROM (m:Movie) WHERE m.year == year
       ORDER BY m.boxoffice DESC
       LIMIT k;
PRINT topK;
}
INTERPRET QUERY topMovies(1939, 10)

Interpret an ad hoc anonymous query

If you plan to run a query only once, you can skip saving it.

The query is not named and does not require parameters.

INTERPRET QUERY () {
topK = SELECT m FROM (m:Movie) WHERE m.year == 1939
ORDER BY m.boxoffice DESC
LIMIT 10;
PRINT topK;
}

Interpret a non-procedural query

Introduced in 4.2, this method lets you run simple queries directly in the GSQL shell.

There is no RUN or INTERPRET command. You simply submit the query.

SELECT m FROM (m:Movie) WHERE m.year == 1939 ORDER BY m.boxoffice DESC LIMIT 10

For more examples, see the 1-Block Query Examples in the GSQL V3 tutorial.

Runtime Engine (Interpreted Queries Only)

If you choose INTERPRET, TigerGraph executes the query using an interpreted engine.

Starting in 4.3, interpreted queries can run using one of two engines:

  • Instruction engine

  • Standard interpret engine

By default, TigerGraph attempts to use the instruction engine. If unsupported features are detected, it automatically switches to the standard engine.

You can explicitly choose the engine using the -mode option:

INTERPRET QUERY topMovies(1939, 10)
INTERPRET QUERY topMovies(1939, 10) -mode instruction
INTERPRET QUERY topMovies(1939, 10) -mode legacy

For full syntax details, see Interpret Query.

Cluster Execution (Installed Queries on Partitioned Graphs Only)

If you install a query and your graph is partitioned across multiple nodes, you can control how TigerGraph distributes the computation.

Cluster Execution Options:

  • Hub-based execution

  • Distributed execution

Distributed execution spreads work across cluster nodes and improves performance when the query touches a large portion of the graph or starts from many vertices.

For more information, see the Distributed Query Mode page.