Skip to main content

Data Grid

The Data Grid API returns individual records from a Data Pool with the convenience of built-in pagination, filtering, and sorting.

Use cases​

You can use the Data Grid API to display data in a table format efficiently. It's ideal for data tables with individual events, orders, or requests, as well as log messages.

Data TablesLog Interfaces
Data table exampleLog interface example

Features​

  • Filtering: Enables users to apply filters to the query to narrow down the results. The filters argument in the query is an array of filter objects, where each filter specifies a column, operator, and value to filter on.
  • Ordering: Enables users to order the results based on a specified column and sort direction. The orderByColumn input field in the query specifies the column to order by, and the sort argument specifies the sort direction. The sort direction can be either ascending (ASC) or descending (DESC).
  • Pagination: Provides built-in cursor-based pagination to allow users to navigate through large data sets. The first argument in the query specifies the maximum number of records to return starting from the given cursor, and the pageInfo object in the response provides information on the current page, the cursor, as well as whether there are more pages available. See our API pagination guide to learn more about pagination.

Usage​

Arguments​

The table below describes the input parameters for the Data Grid API. These parameters allow you to customize your query, including specifying the columns of the data, ordering and filtering the results, and controlling pagination.

FieldTypeRequiredDescription
dataPoolDataPoolInputYes

The Data Pool to be queried.

timeRangeTimeRangeInputNo

The time range for retrieving the records.

timeZoneStringNo

The time zone to use. Dates and times are always returned in UTC, but setting the time zone influences relative time ranges and granularities.

You can set this to "America/Los_Angeles", "Europe/Berlin", or any other value in the IANA time zone database. Defaults to "UTC".

columns array of StringYes

The columns to retrieve.

orderByColumnIntNo

The index of the column to order the table by. The index is 1-based. If not provided, records will be ordered by their timestamp by default.

sortSortNo

The sort order of the rows. It can be ascending (ASC) or descending (DESC) order. Defaults to descending (DESC) order when not provided.

filters array of FilterInputNo

The filters to apply to the records. You may only filter on columns included in the columns array input.

firstIntNo

The number of rows to be returned when paging forward. It can be a number between 1 and 1,000.

afterStringNo

The cursor to use when paging forward.

lastIntNo

The number of rows to be returned when paging forward. It can be a number between 1 and 1,000.

beforeStringNo

The cursor to use when paging backward.

Read more about DataGridInput.

Response​

The Data Grid API responds with a DataGridConnection object that includes headers and rows for a single page of a table. It also allows paging forward and backward to other pages of the table.

FieldTypeNullableDescription
headers array of StringNo

The Data Grid table's headers.

rows array of StringNo

An array of arrays containing the values of the Data Grid table's rows.

queryQueryInfoNo

The Query statistics and metadata.

pageInfoPageInfoNo

The Data Grid table's page info.

edges array of DataGridEdgeNo

The Data Grid table's edges.

nodes array of DataGridNodeNo

The Data Grid table's nodes.

To learn more about implementing pagination, read our pagination in GraphQL guide.

Example​

The following example demonstrates how to use the Data Grid API to query a "list of orders for this month".


Query:
query DataGridQuery($input: DataGridInput!) {
  dataGrid(input: $input) {
    headers
    rows
    pageInfo {
      hasNextPage
      hasPreviousPage
      endCursor
      startCursor
    }
  }
}

Variables:

{
  "input": {
    "dataPool": {
      "name": "TacoSoft Demo Data"
    },
    "timeRange": {
      "relative": "THIS_MONTH"
    },
    "columns": ["timestamp", "order_item_id", "taco_name", "taco_total_price"],
    "orderByColumn": 1,
    "sort": "DESC",
    "filters": [],
    "first": 5
  }
}

Performance considerations​

For the best possible performance, only select the columns that you need to display. Given that Propel is powered by a columnar store, the more columns you select, the slower the query.

If you need to select all the columns of an individual record, consider using the Records by ID API.