AgenticOS: ArcQL Query Language – Token Selection Syntax

February 5, 2026February 26, 2026

ArcQL Query Language – Token Selection Syntax

ArcQL (Arc Query Language) is AgetnticOS’s query language for selecting tokens from places. Every transition preset uses ArcQL to specify which tokens to consume, making it fundamental to understanding how tokens agentic through your Petri nets.

Key Rule: All paths must start with $ (the root) and use == (double equals) for equality. String values use double quotes.

Every ArcQL query follows this structure: FROM $ WHERE condition LIMIT n

Basic Query Syntax

// Select ALL tokens (no filter)
FROM $

// Filter by field value
FROM $ WHERE $.status=="active"

// Numeric comparison
FROM $ WHERE $.amount > 100

// Multiple conditions (AND)
FROM $ WHERE $.status=="pending" AND $.priority=="high"

// Limit results
FROM $ WHERE $.type=="order" LIMIT 10

// Order by field
FROM $ ORDER BY $.timestamp DESC LIMIT 5

Critical Syntax Rules

Syntax Reference Table

Token Structure in ArcQL

Accessing Token Fields

// Access user data (most common)
FROM $ WHERE $.data.status=="active"
FROM $ WHERE $.data.orderId=="ORD-123"
FROM $ WHERE $.data.amount > 100

// Access metadata
FROM $ WHERE $._meta.name=="special-token"
FROM $ WHERE $._meta.type=="Leaf"

Using ArcQL in Inscriptions

{
  "presets": {
    "input": {
      "placeId": "order-queue",
      "host": "my-model@localhost:8080",
      "arcql": "FROM $ WHERE $.data.status==\"pending\" LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  }
}

JSON Escaping: When writing ArcQL in JSON inscriptions, double quotes must be escaped with backslash:

// In JSON, escape inner double quotes with backslash
"arcql": "FROM $ WHERE $.data.status==\"active\""

// The actual query is:
// FROM $ WHERE $.data.status=="active"

take Semantics in Presets

Quick Reference

// ================================
// ArcQL QUICK REFERENCE
// ================================

// Basic selection
FROM $                                    // All tokens
FROM $ LIMIT 1                            // First token

// Equality (strings)
FROM $ WHERE $.data.status=="active"      // $ prefix + == + ""

// Equality (numbers)
FROM $ WHERE $.data.amount > 100          // Numbers: no quotes

// Equality (booleans)
FROM $ WHERE $.data.active == true        // Booleans: no quotes

// Nested access
FROM $ WHERE $.data.customer.name=="John"

// Multiple conditions
FROM $ WHERE $.data.status=="pending" AND $.data.priority=="high"
FROM $ WHERE $.data.status=="active" OR $.data.status=="pending"

// Ordering
FROM $ ORDER BY $.data.timestamp DESC
FROM $ ORDER BY $.data.priority LIMIT 5

// In JSON inscription (escape quotes)
"arcql": "FROM $ WHERE $.data.status==\"pending\""

Summary

$ prefix – All field paths start with $
Double equals – Use == for equality (not single =)
Double quotes – String values use "..." (not single quotes)
Nested access – Use dot notation: $.data.customer.name
Logical operators – AND, OR for complex conditions
LIMIT – Control how many tokens to return
ORDER BY – Sort results before limiting

Leave a Reply Cancel reply