Hodoflow / Developers
Sign in
Browse documentation
Help Center →
Reference GraphQL

factQuery arguments and results

Understand latest versus timeline semantics and every public factQuery argument, PageOfFact field, and Fact field.

View as Markdown

factQuery reads one data model as a logical table. The model slug selects the table, its fields define allowed payload columns, and each Fact is one mapped record. It requires an authenticated service account with api_read.

Operation signature

factQuery(

  dataModelSlug: String!

  mode: String

  timeAxis: String

  since: DateTime

  until: DateTime

  filters: String

  sort: String

  sortDirection: String

  limit: Int

  offset: Int

): PageOfFact
Argument Values Default Meaning
dataModelSlug required string — Model resolved in the credential workspace
mode latest, timeline latest Current row per entity or history
timeAxis observed_at, inserted_at observed_at Timestamp used for the window
since ISO-8601 DateTime mode-dependent Inclusive lower bound
until ISO-8601 DateTime now in timeline Upper bound
filters JSON array encoded as string none At most 20 field/operator/value clauses
sort observed_at, inserted_at, entity_id observed_at Timeline ordering field
sortDirection asc, desc desc Timeline direction
limit integer, maximum 250 50 Page size, also complexity-sensitive
offset non-negative integer 0 Rows to skip

Unknown enumerated values are errors, not silent fallbacks. Pass limit explicitly even though the runtime defaults to 50.

Latest mode

latest returns one most recent row for each non-null entityId. It is useful for current-state views. Rows without entity identity are excluded, and clients must not depend on server ordering from the distinct-per-entity query.

Latest mode is not automatically time-clamped because a current row may be old. Any explicit since or until still applies as a normal filter.

Timeline mode

timeline returns every matching historical row. Sort defaults to newest observed_at first. If no window is supplied, it uses the last 90 days ending now. A requested span wider than 366 days is clamped forward to 366 days.

Always provide a bounded page size and, for repeatable exports, explicit time bounds. Offset pagination is supported; keyset pagination is not.

PageOfFact

The result page exposes:

  • results — selected Fact rows;
  • count — total matching count when requested;
  • hasNextPage and hasPreviousPage;
  • pageNumber and lastPage; and
  • limit — applied page size.

Requesting count can require an additional count query. Ask for it only when the client uses it.

Fact

Public fields include id, dataModelId, entityId, observedAt, insertedAt, and data. The data JSON object contains values mapped to the model's public fields. Lineage and internal execution fields remain outside this logical-table response unless explicitly present in the current GraphQL SDL.

Errors

Bad query syntax/types, unknown model slugs, invalid filters, and cost-limit violations appear in GraphQL's errors array, often with HTTP 200. Invalid tokens and 429 rate limits use transport-level API errors. Keep x-request-id for both.

Use the browsable factQuery endpoint reference for copyable query/variables examples.

Related documentation