docs/src/guide/querying.md

Querying data

Once you have entities in your workspace, you can query them using the CLI.

Getting an entity

To view the full details of a single entity, use firm get followed by the entity's type and ID.

$ firm get person john_doe

Found 'person' entity with ID 'john_doe'

ID: person.john_doe
Name: John Doe
Email: john@doe.com

Listing entities

Use firm list to see all entities of a specific type.

$ firm list task

Found 7 entities with type 'task'

ID: task.design_homepage
Name: Design new homepage
Is completed: false
Assignee ref: person.jane_doe

...

Custom queries

For deeper insights, use firm query which supports a SQL-like query language. This allows you to filter, traverse relationships, sort, and limit results in one expression.

Query syntax

from <type> | <operation> | <operation> | ... | <aggregation>

Available operations

• from <type> - Selects the initial entity set
• where <field> <operator> <value> - Filter entities by field values
• related([degrees]) [<type>] - Traverse relationships
• order <field> [asc|desc] - Sort results
• limit <n> - Limit the number of results

Aggregations

An optional final clause that summarizes the result set:

• select <field>, ... - Extract specific field values
• count [<field>] - Count entities (optionally only those with the field)
• sum <field> - Sum a numeric field
• average <field> - Compute the mean of a numeric field
• median <field> - Compute the median of a numeric field

Examples

Find all incomplete tasks:

$ firm query 'from task | where is_completed == false'

Find tasks assigned to a specific person:

$ firm query 'from task | where assignee_ref == person.john_doe'

Find invoices that are draft or sent:

$ firm query 'from invoice | where status == "draft" or status == "sent"'

Find recent incomplete tasks related to active projects, sorted by due date:

$ firm query 'from project | where status == "in progress" | related(2) task | where is_completed == false | where due_date > 2025-01-01 | order due_date | limit 10'

Count incomplete tasks:

$ firm query 'from task | where is_completed == false | count'

Sum invoice amounts:

$ firm query 'from invoice | where status == "sent" | sum amount'

Extract specific fields:

$ firm query 'from task | where is_completed == false | select @id, name, due_date'

Query operators

You can filter by any field or metadata (@type, @id), traverse relationships multiple degrees deep, and compose operations to build the exact query you need.

Comparison operators:

• == - Equal
• != - Not equal
• > - Greater than
• < - Less than
• >= - Greater than or equal
• <= - Less than or equal

For more details, see the Query reference.