Skip to content

select ¤

FlureeQL Select Clause Grammar

The select clause in FlureeQL determines the structure and content of query results.
It can be either a select object or a select array.

This grammar defines the syntax for FlureeQL select clauses. The types defined below
in this file implement this grammar in Python.

Grammar (EBNF):

    (* Main select clause structure *)
    SelectClause = SelectObject | SelectArray

    (* Select object maps logic variables to expressions *)
    SelectObject = "{" LogicVariable ":" SelectExpressionList "}"
    SelectExpressionList = [SelectExpression {"," SelectExpression}]

    (* Select array contains variables or objects *)
    SelectArray = "[" SelectArrayElement {"," SelectArrayElement} "]"
    SelectArrayElement = LogicVariable | SelectObject

    (* Expression types *)
    SelectExpression = Wildcard | Predicate | NodeObjectTemplate
    NodeObjectTemplate = "{" Predicate ":" SelectExpressionList "}"

    (* Basic elements *)
    LogicVariable = "?" (letter | digit | "-" | "_") {letter | digit | "-" | "_"}
    Predicate = string
    Wildcard = "*"

    (* Character sets *)
    letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
    digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
    string = '"' {character} '"'
    character = letter | digit | "-" | "_" | ":" | "."

Example Queries

Select object - get name and all predicates of best friend¤

  • { "?s": [ "name", { "bestFriend": ["*"] } ] }

Select array - get multiple variables and objects¤

  • ["?s", "?name", "?friend"]
  • [ { "?s": [""] }, { "?friend": [""] } ]

Node object template - nested data structures¤

  • { "schema:address": ["*"] } # Get all address predicates
  • { "bestFriend": ["*"] } # Get all best friend predicates
  • { "bestFriend": [ { "address": ["*"] } ] } # Get address of best friend

Logic variable examples¤

  • "?firstname"
  • "?first-name"
  • "?first_name"
  • "?address-1"

Functions:

Attributes:

LogicVariable module-attribute ¤

LogicVariable: TypeAlias = str

A logic variable name in a FlureeQL query.
Logic variables are strings that begin with a question mark, ?, followed by
alphanumeric characters, hyphens, and underscores. They are used to bind
subjects to variables in the query.

Example Queries

"?firstname"
"?first-name"
"?first_name"
"?address-1"

NodeObjectTemplate module-attribute ¤

NodeObjectTemplate: TypeAlias = dict[Predicate, 'SelectExpressionList']

A node object template in a FlureeQL query.
Node object templates define how to traverse nested predicate values.
They are objects where the keys are predicates, and the values are arrays of
select expressions. This allows for recursive querying of nested data structures.

Example Queries

{ "schema:address": ["*"] }

Return an object that has all predicates for the node that "bestFriend" refers to¤

{ "bestFriend": ["*"] }

Multi-level nested object¤

{ "bestFriend": [ { "address": ["*"] } ] }

Predicate module-attribute ¤

Predicate: TypeAlias = str

A predicate identifier in a FlureeQL query.
A predicate is a string that identifies a property or relationship in the database.

Examples:

"schema:name"
"schema:age"
"schema:friend"

SelectArray module-attribute ¤

SelectArray: TypeAlias = list[SelectArrayElement]

A select array in a FlureeQL query.
A select array is a list containing logic variables or select objects.
When using a select array, each element of the query results will be an array
containing the values for each element in the select array.

Example Queries

["?s", "?name", "?friend"][ { "?s": ["*"] }, { "?friend": ["*"] } ]

SelectArrayElement module-attribute ¤

SelectArrayElement: TypeAlias = LogicVariable | SelectObject

An element in a select array in a FlureeQL query.
An element in a select array can be either a logic variable or a select object.

Example Queries

"?s"

SelectClause module-attribute ¤

SelectClause: TypeAlias = SelectObject | SelectArray

A select clause in a FlureeQL query.
A select clause can be either a select object or a select array.

Example Queries
  • { "?s": [ "name", { "bestFriend": ["*"] } ] }
  • ["?s", "?name", "?friend"]

SelectExpression module-attribute ¤

SelectExpression: TypeAlias = Wildcard | Predicate | 'NodeObjectTemplate'

A select expression in a FlureeQL query.
Select expressions define what data to include in the query results.
They can be:
1. A predicate (e.g., "schema:name") - includes the value of that predicate
2. The wildcard "*" - includes all predicates of the subject
3. A node object template - traverses nested predicate values

Example Queries

["name", { "bestFriend": ["*"] }]

SelectExpressionList module-attribute ¤

SelectExpressionList: TypeAlias = list[SelectExpression]

A list of select expressions in a FlureeQL query.
Used in both select objects and node templates to specify multiple expressions.

Example Queries

["name", "", { "bestFriend": [""] }]

SelectObject module-attribute ¤

SelectObject: TypeAlias = dict[LogicVariable, SelectExpressionList]

A select object in a FlureeQL query.
A select object maps logic variables to arrays of select expressions.
Each logic variable corresponds to a set of subjects, and for each subject,
a JSON object is constructed based on the select expressions.

Example Queries

{ "?s": [ "name", { "bestFriend": ["*"] } ] }

Wildcard module-attribute ¤

Wildcard: TypeAlias = Literal['*']

A wildcard character in a FlureeQL query.
The wildcard character is used to select all predicates of a subject.

Examples:

"*"

is_logic_variable ¤

is_logic_variable(var: str) -> TypeGuard[LogicVariable]

Type guard to check if a string is a valid logic variable.

is_node_object_template ¤

is_node_object_template(var: Any) -> TypeGuard[NodeObjectTemplate]

Type guard to check if a value is a valid node object template.

is_select_array ¤

is_select_array(var: Any) -> TypeGuard[SelectArray]

Type guard to check if a value is a valid select array.

is_select_array_element ¤

is_select_array_element(var: Any) -> TypeGuard[SelectArrayElement]

Type guard to check if a value is a valid select array element.

is_select_object ¤

is_select_object(var: Any) -> TypeGuard[SelectObject]

Type guard to check if a value is a valid select object.