internal-querying
Reference for building a raw query object against a data view: the query grammar, the queryable columns per view, and the additional (unexposed) filters. The agent-facing guidance and examples live in the compiled prompt; this file holds only the reference.
Conditions
The query object skeleton (sort, limit, filters, after/before, …) is shared — see
Query object. This section covers the filters conditions, which the
data API does not expose.
A condition is {"column": value} (equality) or {"column": {"$op": value}}.
- Entries in
filtersare ANDed. To OR or nest, use$or/$and, each taking an array of condition objects:{"$or": [ {…}, {…} ]}. - One operator per condition.
{"col": {"$gte": X, "$lte": Y}}is invalid (read as a JSON value, not a range). Express a range as two conditions — via$and, or the array form offilters:[ {"col": {"$gte": X}}, {"col": {"$lte": Y}} ]. - A key is a predefined filter or a raw column. A registered filter name (
verb,since,person, …) invokes that filter and takes the literal value (it hashes/encodes for you); any other key is a raw column condition. Predefined filters and raw columns compose in onefilters.
| Operator | Meaning |
|---|---|
$eq |
Equal (a bare value is $eq). |
$ne |
Not equal. |
$gt / $gte / $lt / $lte |
Range comparisons. |
$in / $nin |
In / not in a list of values. |
$text |
Substring (LIKE) match — literal text columns only. |
$exists |
Column is not null (true) / is null (false). |
$or / $and |
Group sub-conditions (array of condition objects). |
$has |
A named model relation exists (rarely needed). |
Array columns (agent_ids, activity_ids, members): match an element with the [*] suffix —
{"agent_ids[*]": "<hashed-id>"}.
Statements
| Column | Type | Notes |
|---|---|---|
id |
UUID | Statement UUID (primary key). |
raw |
object | Full xAPI statement. Not for filtering. |
voided |
boolean | The statement has been voided. |
voiding |
boolean | The statement is itself a voiding statement. |
validated |
boolean | Validation has run. |
valid |
boolean | The statement is valid. |
pseudonymized |
boolean | The actor has been pseudonymized. |
actor_id |
Hashed ID | The actor agent. |
verb_id |
Hashed ID | The verb. |
object_id |
Hashed ID | The object (agent or activity). |
type_id |
Hashed ID | The object's activity-type. |
agent_ids |
array of Hashed ID | All related agents — query with agent_ids[*]. |
activity_ids |
array of Hashed ID | All related activities — query with activity_ids[*]. |
registration |
UUID | Registration. |
statement_ref |
UUID | Referenced statement id (nullable). |
store |
string | Store scope (enforced automatically). |
client |
string | Client that recorded it. |
timestamp |
ISO-8601 date-time | The statement's own timestamp. |
stored |
ISO-8601 date-time | Server storage timestamp. |
Additional filters (implemented, not exposed by the API):
| Name | Type | Description |
|---|---|---|
person |
array of Hashed ID | Filter by a whole Person — matches actor_id or object_id against the person's agent hash-ids. |
statementId |
UUID | A single non-voided statement by id (voided=false AND id=…). |
voidedStatementId |
UUID | A single voided statement by id. |
Activities
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The activity IRI (primary key). |
iri |
IRI | The activity IRI (literal). |
definition |
object | The activity definition. Not for filtering. |
type_id |
Hashed ID | The activity-type IRI. |
is_category |
integer (0/1) | Flag: used as a context category. |
is_profile |
integer (0/1) | Flag: is a profile. |
store |
string | Store scope. |
stored |
ISO-8601 date-time | First-seen timestamp. |
updated |
ISO-8601 date-time | Last-updated timestamp. |
No additional filters.
Agents
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The agent IFI (primary key). |
sid_field_1 |
string | Primary IFI field (literal, substring-searchable). |
sid_field_2 |
string | Secondary IFI field (e.g. account homePage). |
sid_type |
string | IFI type (mbox/mbox_sha1sum/openid/account). |
name |
string | Agent/group name (literal). |
is_group |
integer (0/1) | Flag: the actor is a group. |
members |
array of Hashed ID | Group member ids — query with members[*]. |
members_count |
integer | Number of members. |
pseudonymized |
boolean | The agent is pseudonymized. |
person_id |
UUID | Owning person id. |
store |
string | Store scope. |
stored |
ISO-8601 date-time | First-seen timestamp. |
updated |
ISO-8601 date-time | Last-updated timestamp. |
Additional filters (implemented, not exposed by the API):
| Name | Type | Description |
|---|---|---|
person |
array of Hashed ID | All agents of a Person (matches id). |
Activity Profiles
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | Document row id. |
activity_id |
Hashed ID | The owning activity. |
activity_iri |
IRI | The owning activity IRI (literal). |
profile_id |
string | Profile document key (literal). |
content |
string | Document content. |
content_type |
MIME type | Document content-type. |
store |
string | Store scope. |
stored |
ISO-8601 date-time | First-seen timestamp. |
updated |
ISO-8601 date-time | Last-updated timestamp. |
Additional filters — all inherited from the shared document filters and inert on this entity (they target columns this table lacks):
| Name | Type | Description |
|---|---|---|
agent |
Agent IFI | Inert — targets agent_id, absent here. |
person |
array of Hashed ID | Inert — targets agent_id, absent here. |
stateId |
string | Inert — targets state_id, absent here. |
Agent Profiles
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | Document row id. |
agent_id |
Hashed ID | The owning agent. |
agent_sid |
string | The owning agent's IFI (literal). |
profile_id |
string | Profile document key (literal). |
content |
string | Document content. |
content_type |
MIME type | Document content-type. |
store |
string | Store scope. |
stored |
ISO-8601 date-time | First-seen timestamp. |
updated |
ISO-8601 date-time | Last-updated timestamp. |
Additional filters (implemented, not exposed by the API):
| Name | Type | Description |
|---|---|---|
person |
array of Hashed ID | Documents owned by any of a Person's agents (matches agent_id). |
activityId |
IRI | Inert — targets activity_id, absent here. |
stateId |
string | Inert — targets state_id, absent here. |
States
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | Document row id. |
activity_id |
Hashed ID | The owning activity. |
activity_iri |
IRI | The owning activity IRI (literal). |
agent_id |
Hashed ID | The owning agent. |
agent_sid |
string | The owning agent's IFI (literal). |
state_id |
string | State document key (literal). |
registration |
UUID | Registration (nullable). |
content |
string | Document content. |
content_type |
MIME type | Document content-type. |
store |
string | Store scope. |
stored |
ISO-8601 date-time | First-seen timestamp. |
updated |
ISO-8601 date-time | Last-updated timestamp. |
Additional filters (implemented, not exposed by the API):
| Name | Type | Description |
|---|---|---|
person |
array of Hashed ID | States owned by any of a Person's agents (matches agent_id). |
profileId |
string | Inert — targets profile_id, absent here. |
Verbs
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The verb IRI (primary key). |
iri |
IRI | The verb IRI (literal, substring-searchable). |
store |
string | Store scope. |
created_at |
ISO-8601 date-time | Row creation timestamp. |
updated_at |
ISO-8601 date-time | Row update timestamp. |
No additional filters.
Activity Types
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The activity-type IRI (primary key). |
iri |
IRI | The activity-type IRI (literal, substring-searchable). |
store |
string | Store scope. |
created_at |
ISO-8601 date-time | Row creation timestamp. |
updated_at |
ISO-8601 date-time | Row update timestamp. |
No additional filters.
Activity IDs
The activity identifier read-model (lookup / autocomplete; see spec §R1.22).
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The activity IRI. |
iri |
IRI | The activity IRI (literal, substring-searchable). |
is_category |
integer (0/1) | Flag: context-category activity. |
is_profile |
integer (0/1) | Flag: profile activity. |
store |
string | Store scope. |
created_at |
ISO-8601 date-time | Row creation timestamp. |
updated_at |
ISO-8601 date-time | Row update timestamp. |
name |
string | Flattened, all-languages activity name (literal). |
type_id |
Hashed ID | The activity-type IRI. |
No additional filters.
Agent IDs
The agent identifier read-model (lookup / autocomplete; see spec §R1.22).
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | The agent IFI. |
sid_field_1 |
string | Primary IFI field (literal, substring-searchable). |
sid_field_2 |
string | Secondary IFI field (literal). |
sid_type |
string | IFI type. |
store |
string | Store scope. |
created_at |
ISO-8601 date-time | Row creation timestamp. |
updated_at |
ISO-8601 date-time | Row update timestamp. |
name |
string | Agent/group name (literal). |
is_group |
integer (0/1) | Flag: the actor is a group. |
members_count |
integer | Number of members. |
Additional filters (implemented, not exposed by the API):
| Name | Type | Description |
|---|---|---|
person |
array of Hashed ID | All agent-ids of a Person (matches id). |
Document IDs
The document identifier read-model across State / Activity-Profile / Agent-Profile documents.
| Column | Type | Notes |
|---|---|---|
id |
Hashed ID | Document id. |
name |
string | Document key/name (literal, substring-searchable). |
doc_type |
string | activity-profile / agent-profile / state. |
mime_type |
MIME type | Document content-type (literal, substring-searchable). |
store |
string | Store scope. |
created_at |
ISO-8601 date-time | Row creation timestamp. |
updated_at |
ISO-8601 date-time | Row update timestamp. |
No additional filters.