# Entity types

Every record in Coralogix carries two structural labels:

- A **pillar** — the broad category of observability data: `logs`, `spans`, `metrics`, `data`, `binary`, or `profiles`.
- An **entity type** — a finer classification within a pillar (`logs`, `browserLogs`, `auditEvents`, `engineQueries`, `spans`, `cpuProfiles`, `jsonData`, and others).

Pillars and entity types let the platform reason about the **shape** of data without inspecting individual records. Once you know an event's entity type, you know which fields are guaranteed to be present, how the record can be queried, how it's stored, and which features work with it.

## Pillars and the entity types within them

Each pillar groups entity types that share the same fundamental structure and guarantees.

| Pillar       | What it holds                                                                                          | Common entity types                                                                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **logs**     | Time-stamped events with severity — the catch-all for observability records.                           | `logs`, `text`, `browserLogs`, `mobileLogs`, `alerts`, `alertDefs`, `dashboards`, `enrichmentRules`, `notificationDeliveries`, `auditEvents`, `bulkSizes`, `schemaFields`, `quotaEvents`, `engineQueries` |
| **spans**    | OpenTelemetry-style spans with duration and service/operation labels.                                  | `spans`                                                                                                                                                                                                   |
| **metrics**  | Sample-and-label time series.                                                                          | `metrics`                                                                                                                                                                                                 |
| **data**     | Non-time-driven data — aggregation results, lookup tables, anything where time isn't the primary axis. | `jsonData`                                                                                                                                                                                                |
| **binary**   | Opaque files that the platform stores but doesn't structurally query.                                  | `sessionRecordings`, `sourceMaps`, `dsym`, `proguard`, `files`                                                                                                                                            |
| **profiles** | Continuous profiling samples.                                                                          | `cpuProfiles`                                                                                                                                                                                             |

The list above shows the most-common entity types; new ones are added over time as the platform expands. The canonical catalog of every registered entity type — and the JSON schema for each — lives in Coralogix's internal data catalog.

## Schema guarantees

The point of entity types is that they're **a contract**. If a record is in a given pillar, you can rely on certain fields being present without checking.

| Pillar                    | Guaranteed fields                                                                                     | Time partitioning                |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- |
| `logs`                    | `$m.timestamp`, `$m.severity`                                                                         | Yes — by date and hour (`dt/hr`) |
| `spans`                   | `$m.timestamp`, `$m.severity`, `$m.duration`, `$m.endTimestamp`, `$l.serviceName`, `$l.operationName` | Yes — by date and hour (`dt/hr`) |
| `metrics`                 | Sample value and label set                                                                            | Time-series storage              |
| `data` (e.g., `jsonData`) | `$m.cxEventId` (UUID; generated on ingress if missing). **No `$m.timestamp`, no `$m.severity`.**      | No — unpartitioned               |
| `binary`                  | Opaque payload                                                                                        | Storage-only                     |
| `profiles`                | Profiling sample shape                                                                                | Yes — by date and hour           |

The most consequential rule: **time-graphs, alerting, and any feature that assumes a timestamp work for `logs`, `spans`, `metrics`, and `profiles`, but not for `data`.** The `data` pillar (including `jsonData`) is the platform's fallback for results that don't fit a time-driven model — aggregations that dropped the timestamp, lookup tables, exported summaries.

## How entity types are produced

### Direct ingestion

Logs, spans, metrics, binaries, and profiles arrive with their entity type already set by the ingestion pipeline. The pillar and entity type are derived from the integration sending the data.

### DataPrime queries

A [DataPrime](https://coralogix.com/docs/dataprime/introduction/welcome-to-the-dataprime-reference/index.md) query's result entity type depends on its `source` and how the pipeline transforms the rows:

| Query                          | Result entity type                    |
| ------------------------------ | ------------------------------------- |
| \`source logs                  | filter $d.severity == "ERROR"\`       |
| \`source spans                 | limit 100\`                           |
| \`source logs                  | countby $m.severity\`                 |
| \`source system/engine.queries | writeto default/my_queries\`          |
| `source <jsonData dataset>`    | `jsonData` (no time axis to preserve) |

Aggregation commands like `groupby`, `countby`, and `summarize` that don't carry `$m.timestamp` through produce `jsonData` because the time guarantee is broken.

### Lucene queries

Lucene queries always run against the `logs` pillar and produce results of entity type `logs`. To query other entity types, use DataPrime.

### Transformations that change the type

Two paths can shift a record's entity type:

- **Aggregation in DataPrime** — as above, dropping `$m.timestamp` puts the result into `jsonData`.
- **Overwriting a dataset** — `writeto` with **Overwrite** starts a new dataset version, which may have a different entity type than previous versions.

The platform rejects **Append** writes that would mix entity types within a dataset version. Switch to **Overwrite** to start a fresh version with the new type.

## Where entity types appear in the product

Anywhere the platform needs to know what shape of data it's dealing with:

- **[Datasets](https://coralogix.com/docs/user-guides/data-layer/datasets/index.md)** — every dataset is locked to one entity type on first write. Before the first write, the dataset shows entity type `empty`.
- **[Background Queries](https://coralogix.com/docs/user-guides/data-query/background-queries/index.md)** — destination datasets must match the query's result entity type on **Append**. Mismatches are caught before submission.
- **[TCO Optimizer](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/index.md)** — quota and routing rules are keyed by entity type.
- **[Quota rules](https://coralogix.com/docs/user-guides/account-management/payment-and-billing/quota-rules/index.md)** — allocation is per entity type.
- **[Enrichment rules](https://coralogix.com/docs/user-guides/enrichment_rules/index.md)** — enrichment datasets carry their own entity type.
- **[Explore](https://coralogix.com/docs/user-guides/data_exploration/index.md)** — pre-built queries and the time-over-graph view adapt to the dataset's entity type (no time graph for `jsonData`).
- **[Data Usage](https://coralogix.com/docs/user-guides/account-management/payment-and-billing/data-usage/index.md)** — the **Units per entity type** breakdown and CSV export include entity type as a column.