Skip to content

Latest commit

 

History

History
172 lines (158 loc) · 8.14 KB

README.md

File metadata and controls

172 lines (158 loc) · 8.14 KB

QuickGrail Reference

Basic Examples

# Define a constraint to match all vertices with IPs that start with '128.55.12'
%start_ip_constraint = * like '128.55.12.%'
# Find vertices of interest using the constraint defined above
$start_ip = $base.getVertex(%start_ip_constraint);
# Find vertices of interest using the constraint directly
$elevate_me = $base.getVertex(* like '%elevateme%');

# Find paths from $elevate_me to $start_ip of length at most 4
$paths = $base.getPath($elevate_me, $start_ip, 4);

# Print subgraph in query client
dump $paths;
# Output subgraph to file
export > /tmp/paths.dot
dump all $paths

Lexical Structure

  • Integer Literals
    • e.g. 1234
  • String Literals
    • e.g. 'abc', '%127.0.0.1%'
  • Name
    • e.g. dump, type, * (yes "star" is a name..), "a name with space and double quotes"
  • Operators
    • e.g. =, +, +=, -, -=, &, &=
  • Graph Variables
    • Variable name format: $[a-zA-Z0-9_]+
      • e.g. $ip, $1
      • $base is a special immutable variable that represents the whole graph
  • Constraint Variables
    • Variable name format: %[a-zA-Z0-9_]+
      • e.g. %ip, %1

Expressions

  • Graph Expressions
    • graph ::= graph-variable
    • graph ::= graph . graph-method ( argument-list )
    • graph ::= graph ( + | - | & ) graph
  • Constraint Expressions
    • constraint-name ::= %[a-zA-Z0-9_]+
    • constraint-comparison-expression ::= name ( == | != | > | < | >= | <= | like ) string-literal
    • constraint-expression ::= [ not ] constraint-comparison-expression | [ not ] constraint-name
    • constraint ::= constraint-expression [ and | or constraint-expression ]

Commands

  • List existing graphs, constraints, and environment variables
    • list to see all
    • list graph for variables bound to graphs
    • list constraint for constraints that have been defined
    • list env for current enviroment variables
  • Set, unset, and print environment variables
    • env set variable_name integer
    • env unset variable_name
    • env print variable_name
  • Print graph statistics
    • Print vertex count and edge count (in specified graph)
      • stat graph
    • Print mean value of vertex/edge annotation key (in specified graph)
      • stat vertex|edge <key> mean graph
    • Print standard deviation of values for vertex/edge annotation key (in specified graph)
      • stat vertex|edge <key> std graph
    • Print histogram of values of vertex/edge annotation key (in specified graph)
      • stat vertex|edge <key> histogram graph
    • Print distribution of values of vertex/edge annotation key (in specified graph)
      • stat vertex|edge <key> distribution <number of bins> graph
      • distribution divides the values from minimum to maximum into specified number of sub-range bins
  • Print graph as a SPADE Graph
    • dump graph
    • using all prints entire graph, even if it exceeds limit in exportLimit environment variable
  • Print constraint
    • dump constraint
  • Remove a list of variables (graph or constraint)
    • erase (graph)+
  • Remove all variables
    • reset workspace
  • Execute query directly in the underlying storage's language
    • native 'query_in_single_quotes'

Methods

Method Declaration Notation

return-type method-name ( argument-type formal-argument, ... )

Graph Methods

  • graph getVertex ( )
    • Get all the vertices
      • e.g. $2 = $1.getVertex()
  • graph getVertex ( constraint constraint )
    • Get all vertices that match a constraint
      • e.g. $2 = $1.getVertex(* LIKE '%firefox%')
  • graph getMatch ( graph otherGraph, string annotation, ... )
    • Get vertices in operand and otherGraph that have all annotation keys specified and the values of those keys match
      • e.g. $3 = $1.getMatch($2, 'pid', 'ppid') returns all vertices in $1 or $2 if a vertex in the other graph had the same values for annotation keys pid and ppid
    • NOTE: Experimental
  • graph getEdge ( )
    • Get all the edges
      • e.g. $2 = $1.getEdge()
  • graph getEdge ( constraint constraint )
    • Get all the edges that match a constraint
      • e.g. $2 = $1.getEdge(operation = 'write')
  • graph collapseEdge ( string annotation, ... )
    • Collapse edges with regard to the annotations
      • e.g. $2 = $1.collapseEdge('type', 'operation')
  • graph getEdgeEndpoints ( )
    • Get all the vertices that are endpoints of edges
      • e.g. $2 = $1.getEdgeEndpoints()
  • graph getEdgeSource ( )
    • Get all the vertices that are source endpoints of edges
      • e.g. $2 = $1.getEdgeSource()
  • graph getEdgeDestination ( )
    • Get all the vertices that are destination endpoints of edges
      • e.g. $2 = $1.getEdgeDestination()
  • graph getLineage ( graph sourceVertices [ , int maxDepth ] , string direction )
    • Get lineage of a set of source vertices
    • direction can be 'ancestor'(or 'a') / 'descendant' (or 'd') / 'both' (or 'b').
      • e.g. $2 = $base.getLineage($1, 3, 'b') or $2 = $base.getLineage($1, 'b') to implicitly use maxDepth environment variable
  • graph getPath ( graph sourceVertices, ( graph destinationVertices [ , int maxDepth ] )+ )
    • Get paths from a set of source vertices to a set of destination vertices, restricted to those that pass through specified intermediate vertices
      • e.g. $3 = $base.getPath($1, $2, 5)
      • e.g. $4 = $base.getPath($1, $2, 9, $3) with a maximum path length between $1 and $2 of 9, and maximum path length between $2 and $3 implicitly defined by maxDepth environment variable
  • graph getShortestPath ( graph sourceVertices, graph destinationVertices[, int maxDepth] )
    • Get the shortest path from a set of source vertices to a set of destination vertices
    • NOTE: Currently this finds a short path, but not the shortest path
      • e.g. $3 = $somePath.getShortestPath($1, $2, 5) or $3 = $somePath.getShortestPath($1, $2) to implicitly use maxDepth environment variable
  • graph getSubgraph ( graph skeletonGraph )
    • Get all vertices and edges that are spanned by skeletonGraph
      • e.g. $2 = $base.getSubgraph($1)

  • graph vertexSubset ( int from, int to )

    • Get the vertex subset (ordered by id) between from (inclusive), and to (exclusive)

  • graph edgeSubset ( int from, int to )

    • Get the edge subset (ordered by id) between from (inclusive), and to (exclusive)

  • graph vertexSample ( int sampleSize )

    • Get the randomly sampled vertex subset of size sampleSize

  • graph edgeSample ( int sampleSize )

    • Get the randomly sampled edge subset of size sampleSize

  • graph transform ( name transformer, string initializationArgument[, argument]*)

    • Use a pre-defined transformer to return a rewritten version of the graph.
    • Arguments can be graph variables, integers, or strings.
      • e.g. $2 = $1.transform(DropKeys, 'keys=uid,gid') copies the vertices and edges in $1 to $2, droppping annotations with uid or gid as the key.
      • e.g. $3 = $2.transform(Prune, '', $1, 10, 'both') prunes graph $1 from $2 upto max depth 10 in both directions.

Functions

  • graph vertices ( string vertexHash, ... )
    • Get all vertices specified by their hashes
      • e.g. $1 = vertices('815fd285f16cce9ab398b5b2ce5d2d03', '087b22992d4d871dc8c9ccd837132c6a')
  • graph edges ( string edgeHash, ... )
    • Get all edges specified by their hashes
      • e.g. $1 = edges('b161b03a4365faf44d8cdd3713f811e9', 'b161b03a4365faf44d8cdd3713f811e0')

Operators

  • Graph Union +, +=
    • e.g. $3 = $1 + $2
    • e.g. $b += $a
  • Graph Intersection &, &=
    • e.g. $3 = $1 & $2
    • e.g. $b &= $a
  • Graph Difference -, -=
    • e.g. $3 = $1 - $2
    • e.g. $b -= $a