GSQL Code Cookbook

This section provides production-ready GSQL snippets with detailed comments explaining the syntax and logic.

1. Schema Definition Patterns

Basic Schema with Attributes

gsqlterminal
Copy
CREATE VERTEX User (PRIMARY_ID id STRING, name STRING, age INT) WITH STATS="OUTDEGREE_BY_EDGETYPE"
CREATE VERTEX Post (PRIMARY_ID id STRING, content STRING, created_at DATETIME)
CREATE DIRECTED EDGE FOLLOWS (FROM User, TO User, connect_day DATETIME)
CREATE UNDIRECTED EDGE AUTHORED (FROM User, TO Post)

CREATE GRAPH SocialGraph (*)

Map and List Attributes

gsqlterminal
Copy
// Using collections inside a vertex
CREATE VERTEX Company (
  PRIMARY_ID id STRING, 
  name STRING, 
  metadata MAP<STRING, STRING>, // Store dynamic key-value pairs
  tags LIST<STRING>             // Store multiple labels
)

2. Data Loading Patterns

Loading from CSV

gsqlterminal
Copy
CREATE LOADING JOB load_social FOR GRAPH SocialGraph {
  DEFINE FILENAME file1 = "/path/to/users.csv";
  LOAD file1 TO VERTEX User VALUES($0, $1, $2) USING SEPARATOR=",", HEADER="true", EOL="\n";
  LOAD file1 TO EDGE FOLLOWS VALUES($0, $3, $4);
}

Loading with Data Transformation

gsqlterminal
Copy
CREATE LOADING JOB load_posts FOR GRAPH SocialGraph {
  DEFINE FILENAME f;
  // Using gsql_upper to normalize data during load
  LOAD f TO VERTEX Post VALUES($0, gsql_upper($1), $2);
}

3. Query Patterns: The Power of Accumulators

Summing Neighbors (The Counter Pattern)

gsqlterminal
Copy
CREATE QUERY follower_count(VERTEX<User> u) FOR GRAPH SocialGraph {
  SumAccum<INT> @@follower_count;
  
  Start = {u};
  
  // Hop to followers and increment global counter
  Followers = SELECT t FROM Start:s -(FOLLOWS:e)-> User:t
              ACCUM @@follower_count += 1;
              
  PRINT @@follower_count;
}

Finding Top-K (The Leaderboard Pattern)

gsqlterminal
Copy
CREATE QUERY top_influencers(INT k) FOR GRAPH SocialGraph {
  // HeapAccum sorts by the first parameter (INT) in descending order (DESC)
  HeapAccum<UserScore>(k, score DESC) @@top_k;
  
  TYPEDEF TUPLE<VERTEX<User> u, INT score> UserScore;
  SumAccum<INT> @influence_score;

  Users = {User.*};
  
  // Calculate scores based on outdegree
  Result = SELECT s FROM Users:s
           ACCUM s.@influence_score = s.outdegree("FOLLOWS")
           POST_ACCUM @@top_k += UserScore(s, s.@influence_score);
           
  PRINT @@top_k;
}

Breadth-First Search (BFS)

gsqlterminal
Copy
CREATE QUERY find_friends_at_distance(VERTEX<User> source, INT dist) FOR GRAPH SocialGraph {
  OrAccum @visited = false;
  SetAccum<VERTEX<User>> @@current_layer;
  
  Start = {source};
  Start = SELECT s FROM Start:s ACCUM s.@visited = true;
  
  WHILE Start.size() > 0 AND dist > 0 DO
    Start = SELECT t FROM Start:s -(FOLLOWS:e)-> User:t
            WHERE t.@visited == false
            ACCUM t.@visited = true;
    dist = dist - 1;
  END;
  
  PRINT Start; // Returns vertices at exactly 'dist' hops
}

4. Vector Search & Similarity

Cosine Similarity Search

gsqlterminal
Copy
CREATE QUERY vector_search(LIST<DOUBLE> target_vector, INT top_k) FOR GRAPH SocialGraph {
  // Use Cosine Similarity via GSQL built-in or custom expression
  HeapAccum<Result>(top_k, sim DESC) @@top_results;
  TYPEDEF TUPLE<VERTEX<User> u, DOUBLE sim> Result;

  Users = {User.*};
  
  Result = SELECT s FROM Users:s
           ACCUM @@top_results += Result(s, cosine_similarity(s.embedding, target_vector));
           
  PRINT @@top_results;
}

[!TIP] Always use POST_ACCUM when you need to perform actions after the traversal, such as populating a HeapAccum or updating vertex attributes based on aggregated values.