Events and collections

GraphJSON has a deliberately small data model: workspaces contain collections, and collections contain timestamped JSON events.

Workspaces#

A workspace owns:

one API key
collections and their retention policies
dashboards, saved queries, and alerts
integrations and team access

API requests authenticated with the workspace key can operate on that workspace’s data. Team members work against the same collections and saved analytics.

Collections#

A collection is a named stream of related events. It is the primary boundary for organization, retention, exploration, and SQL.

For example:

product_events
billing_events
application_logs

The collection name is sent with each ingestion request:

{
  "collection": "product_events",
  "timestamp": 1785081600,
  "json": "{\"event\":\"feature_used\",\"feature\":\"exports\"}"
}

Collections do not require a declared schema. Two events may have different fields, although consistent shapes are easier to analyze.

Events#

An event has two user-controlled parts:

a Unix timestamp in seconds
a serialized JSON object

GraphJSON also associates it with the authenticated workspace and the destination collection.

A common product event looks like:

{
  "event": "report_exported",
  "user_id": "usr_42",
  "account_id": "acct_7",
  "format": "csv",
  "row_count": 842
}

The same payload supports multiple questions: exports over time, unique exporting accounts, format share, or average row count.

The virtual `all_events` collection#

all_events represents all events in the workspace. Use it when you intentionally need to query across collection boundaries:

SELECT count()
FROM all_events
WHERE toDateTime(timestamp) >= subtractDays(now(), 7)

Specific collection names are usually clearer and faster to reason about:

SELECT count()
FROM product_events
WHERE JSONExtractString(json, 'event') = 'report_exported'

Collections are not event types#

Do not create a new collection for every action. Prefer:

collection: product_events
event: signup_completed

collection: product_events
event: report_exported

over:

collection: signup_completed
collection: report_exported

An event property lets you filter and compare related behavior in one place. Create a separate collection when ownership, sensitivity, retention, or analysis patterns are genuinely different.

What a collection controls#

Collection settings include a human-readable description and optional retention period. Deleting a collection removes the underlying events for that collection.

Dashboards and saved queries are separate resources. If they refer to a deleted or renamed collection, update or remove them as part of the same change.