syntax-reference.md

J-Expr Syntax Reference

Core syntax reference for J-Expr, the JSON expression syntax for HashQL.

Expression Types

J-Expr maps JSON types to expression semantics:

JSON Type	J-Expr Meaning
String	Path/identifier
Array	Function call
Object	Data constructor (with # keys)

Paths (String Expressions)

Strings are parsed as paths or identifiers.

Simple Identifiers

"x"
"myVariable"
"entity"

Dotted Paths

Access nested fields:

"vertex.id"
"vertex.id.entity_id"
"entity.properties.name"

Namespaced Paths

Use :: for namespacing:

"Std::String"
"Std::Collections::HashMap"

Rooted paths start with :: (absolute reference):

"::core::types::String"
"::graph::head::entities"
"::graph::tmp::decision_time_now"

Function Calls (Array Expressions)

Arrays represent function calls: [function, arg1, arg2, ...]

Basic Calls

["add", {"#literal": 1}, {"#literal": 2}]
["not", {"#literal": true}]
["concat", {"#literal": "hello"}, {"#literal": " world"}]

Namespaced Functions

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]
["::core::math::sqrt", {"#literal": 16}]

Nested Calls

["add", ["multiply", { "#literal": 2 }, { "#literal": 3 }], { "#literal": 4 }]

Labeled Arguments

Use : prefix for named/labeled arguments.

Object syntax:

["greet", { ":name": { "#literal": "Alice" }, ":greeting": { "#literal": "Hello" } }]

Shorthand string syntax:

["func", ":varName"] // References variable "varName" as labeled argument

Operators

Comparison

["==", "left", "right"]
["!=", "left", "right"]
[">", {"#literal": 5}, {"#literal": 3}]
["<", "a", "b"]
[">=", "x", {"#literal": 0}]
["<=", "y", {"#literal": 100}]

Logical

["and", {"#literal": true}, {"#literal": false}]
["or", "condition1", "condition2"]
["not", "flag"]

Arithmetic

["add", {"#literal": 1}, {"#literal": 2}]
["sub", {"#literal": 5}, {"#literal": 3}]
["multiply", {"#literal": 2}, {"#literal": 3}]
["div", {"#literal": 10}, {"#literal": 2}]

Graph Query Patterns

Fetching Entities

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

Filtering

[
  "filter",
  "entities",
  [
    "fn",
    { "#tuple": [] },
    { "#struct": { "entity": "_" } },
    "_",
    ["==", "entity.draft_id", { "#literal": null }],
  ],
]

Property Access

Use dotted paths:

"vertex.id.entity_id"
"entity.properties.name"

Complete Examples

Entity Query with Filter

[
  "let",
  "entities",
  ["::graph::head::entities", ["::graph::tmp::decision_time_now"]],
  [
    "filter",
    "entities",
    [
      "fn",
      { "#tuple": [] },
      { "#struct": { "e": "_" } },
      "_",
      ["==", "e.archived", { "#literal": false }],
    ],
  ],
]

Nested Conditional

[
  "let",
  "value",
  { "#literal": 42 },
  [
    "if",
    [">", "value", { "#literal": 0 }],
    [
      "if",
      ["<", "value", { "#literal": 100 }],
      { "#literal": "in range" },
      { "#literal": "too high" },
    ],
    { "#literal": "too low" },
  ],
]

Multiple Variable Bindings

[
  "let",
  "x",
  { "#literal": 1 },
  [
    "let",
    "y",
    { "#literal": 2 },
    ["let", "z", ["add", "x", "y"], ["multiply", "z", { "#literal": 2 }]],
  ],
]

Related References

• Special Forms - Control flow (if, let, fn, type, use, etc.)
• Data Constructors - Typed data (#literal, #struct, #tuple, #list, #dict)
• Type DSL - Type annotation syntax

Source Files

• Expression parser: libs/@local/hashql/syntax-jexpr/src/parser/
• String/path parser: libs/@local/hashql/syntax-jexpr/src/parser/string/
• Array parser: libs/@local/hashql/syntax-jexpr/src/parser/array/