TigerGraph
Querying Overview
Qarbine supports direct, native TigerGraph GSQL queries and API access. Native interactions are the only real way to access the full power of TigerGraph. Qaarbine provides several alternatives to interact with the TigerGraph database:
- TigerGraph SELECT query,
- TigerGraph stored query,
- TigerGraph API oriented query, and
- Qarbine convenience query.
These different styles are discussed in more detail below.
Vector Query Prerequisites
For vector related queries, prior to using Qarbine’s embeddings(...) macro function or the SQL-like query function nearText(...), the Qarbine Administrator must first configure “AI Assistant(s)”. The AI Assistants provide access to various popular Generative AI services and are referenced using an alias. Check with your Qarbine administrator for which ones are available and their proper use. For example, when using dynamic query vector embeddings, the model used by the AI Assistant must be compatible with the one used to generate the original embedding values in the database.
GSQL SELECT Support
General Querying
The TigerGraph SELECT queries are run through the TigerGraph interpreted query interface. The effective data payload to the interface is shown below.
INTERPRET QUERY () FOR GRAPH <graphName> { <selectQuery> }
The graph name defaults to the value set in the Qarbine Date service. It secondarily looks for the generic variable “database” (which maps to a TigerGraph graph name). See below for details. Remember to always end your GSQL statements with a semicolon.
You can give a source vertex set an alias by appending the alias after a colon:. Although declaring an alias is optional, it is strongly recommended that you declare them. In the later clauses of the SELECT block, you can only refer to vertex sets in the FROM clause by their aliases.
TigerGraph does not support string literals being single quoted. If you are using Qarbine formulas or Qarbine variables (@name) in a query specification then this
select a.name, a.isBlocked, p into acct from Account:a -(hasPhone:e)- Phone:p
WHERE a.name == @name;
print acct;
needs to use the doubleQuote() macro function to emit the desired string literal as shown below.
select a.name, a.isBlocked, p into acct from Account:a -(hasPhone:e)- Phone:p
WHERE a.name == [! doubleQuote(@name) !];
print acct;
Any “@” character that is part of the regular TigerGraph GSQL query needs to be doubled up because the “@” character is the prefix for Qarbine variables.
Vector Querying
A sample stored query definition using vector embeddings is
CREATE QUERY find_similar_items(
LIST<FLOAT> input_embedding, FLOAT similarity_threshold)
FOR GRAPH Item_Graph {
OrAccum @@visited;
SetAccum<VERTEX<item>> @@@@result;
start = {item.*};
result = SELECT tgt
FROM start:s
WHERE
tg_similarity_accum(s.embedding, input_embedding, "cosine") > similarity_threshold
ACCUM tgt.@visited += TRUE,
@@@@result += tgt;
PRINT @@@@result;
}
The “@@@@” above will end up as “@@” in the final query. The double “@” characters are required because the “@” character is the prefix for Qarbine variables.
In this query:
- We pass the input_embedding as a LIST<FLOAT> parameter to the query.
- The tg_similarity_accum function is used to compare the input_embedding with the embedding attribute of each item vertex.
- The "cosine" similarity measure is specified as the third argument to tg_similarity_accum.
- Items with a similarity score above the threshold are selected and added to the result set.
To use this stored query, call it with an embedding vector and a similarity threshold:
RUN QUERY find_similar_items( [0.1, 0.2, 0.3, ...], 0.8)
See the graph data science support functions at
https://docs.tigergraph.com/graph-ml/3.10/intro/
and vector functions at
https://docs.tigergraph.com/gsql-ref/4.1/querying/func/vector-functions
Further Information
For more information see
https://docs.tigergraph.com/gsql-ref/4.1/querying/select-statement/
https://docs.tigergraph.com/gsql-ref/current/querying/select-statement/sql-like-select-statement
Stored Queries
TigerGraph supports storing procedural code as “stored queries”. These can be run via
The queryArgumentsMap is a JSON structure with names and values of the form
The names correspond to the definition of the stored query. You can use the convenience queries below or the TigerGraph console to obtain the details of a particular stored query.
API Oriented Queries
Overview
Qarbine provides a convenient way to interact with the lower level TigerGraph API. The form of the query specification is
{
action: 'actionToPerform',
graph: 'graphName', ← optional
action arguments 0..n
}
The specification is a simple JSON like structure. Either single or double quotes may be used but proper comma syntax is required.
For API calls which have a graph context, the Qarbine Data Service’s ‘database’ field provides the default name of the graph. Otherwise you may specify a “graph” field in the specification.
The various interactions are described below along with links to corresponding TigerGraph documentation pages and an example. A few of the optional parameters are on lines starting with ‘//’.
getSchemaMetaData
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_show_graph_schema_metadataA sample query specification is shown below.
{
action: 'getSchemaMetaData',
vertexEdges: true,
//onlyNames: true
//include: ['Account', 'Industry']
}
The onlyNames and include arguments are Qarbine extensions which can reduce the amount of the output. The onlyNames argument takes precedence. For example, sometimes you are just interested in the names and not the details. The details can be filtered based on the include list. The resulting object has the fields vertexTypes and edgeTypes each containing a list. If you want edge information included with each vertex then set vertexEdges to true.
getQueryMetadata
https://docs.tigergraph.com/dev/restpp-api/built-in-endpoints#get-query-metadataA sample query specification is shown below.
{
action: 'getQueryMetadata',
query : 'CustomerJourney'
}
The parameters of the 'CustomerJourney' query can be obtained via the ‘getQueryMetadata’ query. The parameters returned are shown below.
{
campaignTypes: { max_count: 2147483647, min_count: 0, type: 'STRING' },
customer: { id_type: 'Contact', is_id: 'true', min_count: 0, type: 'STRING'},
endTime: { min_count: 0, type: 'STRING' },
query: { default: 'CustomerJourney', type: 'STRING' },
startTime: { min_count: 0, type: 'STRING' }
}
runNamedQuery
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_run_an_installed_query_getThe general form of the query specification is shown below.
{
action: 'runNamedQuery',
action arguments 0..n
}
You must include any query parameters in the specification. For details see
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_query_parameter_passing
An example query specification is shown below
{
action: 'runNamedQuery',
query: 'CustomerJourney',
customer : "00536000008Ge5aAAC" ,
campaignTypes: "Event",
startTime :"2018-06-01",
endTime :"2018-10-01"
}
For matching multiple campaign types use a CSV format such as
campaignTypes: "Event,Webinar",
runDynamicQuery
This is a variation of runNamedQuery. Instead of passing the name of a stored query you pass the native GSQL of the form
INTERPRET QUERY ( <arguments> ) FOR GRAPH <graphName> { <statements> }
With this approach you can pass parameters as specification arguments rather than have them as part of the overall SELECT string. Any “$GRAPH” string is replaced prior to execution.
An example query specification is shown below
{
action: 'runDynamicQuery',
query: 'INTERPRET QUERY (INT someInteger) FOR GRAPH MyGraph {\nPRINT someInteger;\n}',
someInteger: 1234
}
getVertices
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_retrieve_a_vertexAn example query specification is shown below
{
action: 'getVertices',
sourceType: 'Account',
sourceId: '0013600001rz2P8AAI',
sort : 'Name',
limit: 10,
select : 'Name,Industry,BillingCity,BillingCity,BillingCountry'
}
When using select, to include the vertex identifier and type in the output use the aliases vid and vtype respectively.
getVertexWithId
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_retrieve_a_vertexAn example query specification is shown below
{
action: 'getVertexWithId',
sourceType: 'Contact',
sourceId: '0033600001oBXMPAA4',
select: 'Name'
}
getVertexEdges
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_list_edges_of_a_vertex
****
An example query specification is shown below
{
action: 'getVertexEdges’,
sourceType: 'Account',
sourceId: '0013600001rz2P8AAI'
//edgeType: 'Has',
//targetType: 'Opportunity',
// limit: 10,
// filter: …,
// edgeVertices: true
}
A sample result is shown below.
The edgeVertices argument is used by Qarbine to retrieve the referenced vertex objects. If true then the answer set is expanded with a vertex field as shown below. This is a very efficient way to automatically retrieve relevant graph data.
getEndpoints
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_list_all_endpointsAn example query specification is shown below
{
action: 'getEndpoints',
type: ‘builtin’
}
The ‘type’ argument is optional and may be dynamic, static, or builtin.
getGraphStatistics
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_show_query_performanceAn example query specification is shown below
{
action: 'getGraphStatistics',
seconds: 60
//segments: 2
}
runBuiltin
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_graphsAn example query specification is shown below
{
action: 'runBuiltin'
//realtime: true
}
A ‘realtime’ value of true forces built-in functions to rerun queries instead of using cached data, which is resource-intensive but more accurate if the graph is frequently updated.
The following retrieves the count for each vertex type sorted in highest to lowest (descending) count order.
{
function: 'stat_vertex_number',
type: '*',
sort: '-count'
}
Use the ‘-’ prefix to request a descending sort. The following retrieves the attributes for each vertex type sorted in A-Z (ascending) order. A ’*’ returns attributes for all types or you may specify a specific type.
{
action: 'runBuiltin',
function: 'stat_vertex_attr',
type: '*',
sort: 'v_type'
}
The following retrieves the count for each edge type sorted in highest to lowest count order. To sort by edge name use sort: ‘e_type’. You may optionally specify a from_type and a to_type.
{
action: 'runBuiltin',
function: 'stat_edge_number',
type: '*',
sort: '-count'
}
The following retrieves the edge attributes. A type of ’*’ returns attributes for all types or you may specify a specific type. You may optionally specify a from_type and a to_type.
{
action: 'runBuiltin',
function: 'stat_edge_attr',
type: 'is_active_as',
sort: ‘e_type’
}
getShortestPath
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_find_shortest_pathThis action is similar to the getAllPaths below but only the shortest one, if any, is returned.
getAllPaths
https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_find_all_pathsAn example query specification is shown below
{
action: 'getAllPaths',
"source": {"type":"Campaign","id":"70136000000m4ZIAAY"},
"target": {"type":"CampaignMember","id":"00v3600001OQMm9AAH"},
//"targets":[{"type":"VidUser","id":"0"}, {"type":"VidUser","id":"3"}],
//"edgeFilters":[{"type":"User_Video","condition":"rating > 5 and date_time > 1000"}],
"maxLength": 4
}
toVertexSet
https://docs.tigergraph.com/gsql-ref/current/querying/func/vertex-methods#_to_vertex_setA sample use of this function is shown below.
// https://docs-legacy.tigergraph.com/dev/gsql-ref/querying/accumulators
// We MUST double the @ character to avoid it looking like a Qarbine variable
SetAccum<STRING> @@@@stringSetAccum;
@@@@stringSetAccum += "0013600001xlUzuAAE";
@@@@stringSetAccum += "0013600001mz6i8AAA";
S2 = to_vertex_set ( @@@@stringSetAccum, "Account");
PRINT S2;
The resulting ‘@@stringSetAccum’ refers to a global accumulator. The name of a global accumulator begins with ‘@@’. The name of a vertex-attached accumulator begins with a single ‘@’. Additionally, a global accumulator may be declared to be static.
General Convenience Queries
Qarbine provides many shortcut convenience queries to access meta data about your database.
Graphs
To get a list of graphs run
list graphs
General Statistics
To get a list of vertex and edge statistics run
describe stats
Privileges
To get a list of privileges run
describe privileges
Groups
To get a list of groups run
describe groups
Roles
To get a list of roles run
describe roles
Users
To get a list of users run
describe users
Component Versions
To get a list of component versions run
describe versions
Data Sources
To get a list of TigerGraph data sources run
describe dataSources
Metrics
To get a list of system metrics run
describe metrics
Packages
To get a list of packages run
describe packages
Graph Specific Convenience Queries
Collections
To get a list of collections run
list collections
To get details on a particular collection run
describe collection <name>
To get details on all collections run
describe collections
Vertex Count
To get the number of instances of a vertex type run
vertexCount <vertexType>
For example,
Edge Count
To get the number of instances of an edge type run
edgeCount<vertexType>
Edge Stats
For example,
edgeCount belongs_to
Queries
To get a list of stored query details run
describe queries
Query Details
To get the details of a stored query run
describe query <name>
Indices
To get a list of index details run
describe indices
Special Data Handling Pragmas
Some date values may be stored as ISO strings. To have Qarbine convert these values into real dates for analysis and formatting you can specify lines at the top of the query as shown below.
#pragma convertDateFields CSV list
Note that the conversion currently only happens to the first level objects. The Qarbine macro function isoDate(isoString) can be used to convert other date strings into date objects. A sample ISO date string is "2022-06-03T18:41:06.334Z".
Here is an example of a query which returns date-like data as heir default strings.
rez = select c from Contact:c limit 5;
print rez;
A sample element is shown below.
The CreatedDate and LastModifiedDate values are just strings and not real date objects. Real dates can be returned using this query.
#pragma convertDateFields CreatedDate, LastModifiedDate
rez = select c from Contact:c limit 5;
print rez;
The adjusted dates are shown below.
The objects processed by the Qarbine template are then real date objects which are directly usable for formatting and with various date functions.
Troubleshooting
404 Status
The 404 error indicates a ‘not found’ status.
500 Status
A 500 error may indicate that your cluster is not running.
502 Status
A 502 error may indicate that your cluster is not running.
ID Querying
If the Person vertex has the identifier as an attribute then try this syntax
SELECT p FROM Person:p WHERE p.id == 1
If the identifier is not selected as attribute then try using the syntax below
SELECT p FROM Person:p WHERE p == 1
Connectivity Errors
The error below indicates to check the TigerGraph console for the server status and also to cross reference the Qarbine data service’s configuration settings.
GSQL Online Tool Verification
Run the query in the TigerGraph GSQL tool and review its results. Note that any single ‘@’ needs to be doubled up because of Qarbine’s scanning for variables.
References
https://www.tigergraph.comhttps://docs.tigergraph.com/dev/gsql-ref
https://docs.tigergraph.com/gsql-ref/4.1/querying/select-statement/
https://docs.tigergraph.com/gsql-ref/current/querying/select-statement/
https://docs.tigergraph.com/gsql-ref/current/querying/select-statement/sql-like-select-statement