Order Time Buckets

The orderTimeBuckets query provides time-series aggregation of orders, grouping them into configurable time intervals. It's designed for analytics dashboards, charts, and trend analysis.

Query Signature

query OrderTimeBuckets(
  $organizationId: Int!
  $interval: TimeBucketInterval!
  $dateField: String!
  $start: DateTime!
  $end: DateTime!
  $includeEmpty: Boolean
  $includeSummary: Boolean
  $filter: String
  $search: String
) {
  orderTimeBuckets(
    organizationId: $organizationId
    interval: $interval
    dateField: $dateField
    start: $start
    end: $end
    includeEmpty: $includeEmpty
    filter: $filter
    search: $search
  ) {
    totalCount
    buckets {
      bucketStart
      bucketEnd
      count
      summary {
        totalWeight
        totalPieces
        totalQuantity
        totalIncome
        totalExpense
        totalProfit
      }
      orders(take: 10, orderBy: "created desc") {
        items {
          orderId
          trackingNumber
          created
        }
        totalCount
      }
    }
  }
}

Parameters

Parameter	Type	Required	Default	Description
organizationId	Int	Yes	—	Organization to query
interval	TimeBucketInterval	Yes	—	Time interval for bucketing
dateField	String	Yes	—	Date field to group by
start	DateTime	Yes	—	Range start (inclusive)
end	DateTime	Yes	—	Range end (exclusive)
includeEmpty	Boolean	No	true	Include buckets with zero orders
filter	String	No	—	Lucene filter applied to orders
search	String	No	—	Full-text search applied to orders

TimeBucketInterval

Value	PostgreSQL Interval	Max Buckets
Minutes5	5 minutes	288
Minutes15	15 minutes	672
Minutes30	30 minutes	1,344
Hour1	1 hour	744
Hours4	4 hours	744
Day1	1 day	366
Week1	7 days	104
Month1	1 month	60

If the date range × interval exceeds the maximum bucket count, the query returns an error with a suggestion to narrow the range or use a larger interval.

dateField

Supported values:

Value	Description
created	Order creation date
lastModified	Last modification date
lastOrderStatusModified	Last status change date
customValues.<key>	Any JSONB custom value containing a date (e.g., customValues.ETA, customValues.pickupDate)

Custom value dates must match the pattern YYYY-MM-DD... and are cast to timestamp at query time.

Response Types

OrderTimeBucketsResult

Field	Type	Description
totalCount	Int	Number of buckets returned
buckets	[OrderTimeBucket]	Array of time buckets

OrderTimeBucket

Field	Type	Description
bucketStart	DateTime	Bucket start time (UTC)
bucketEnd	DateTime	Bucket end time (UTC)
count	Int	Number of orders in this bucket
summary	OrderTimeBucketSummary?	Aggregate summary (only populated when summary is selected)
orders	CollectionSegment<Order>	Paginated orders within this bucket

OrderTimeBucketSummary

Field	Type	Description
totalWeight	Decimal	Sum of order weights
totalPieces	Decimal	Sum of pieces
totalQuantity	Decimal	Sum of quantities
totalIncome	Decimal	Sum of income charges
totalExpense	Decimal	Sum of expense charges
totalProfit	Decimal	Income minus expense

Performance

The summary fields are only computed when explicitly selected in the GraphQL query. If you only need counts, omit the summary selection to avoid the join to the vw_order_summary view.

Data Source

Summary data is sourced from the vw_order_summary database view, which pre-aggregates totals from orders, commodities, and charges. The view includes:

• OrderId, OrganizationId, OrderStatusId, IsDraft
• Created, LastModified, LastOrderStatusModified
• CustomValues (JSONB)
• TotalWeight, TotalPieces, TotalQuantity
• TotalIncome, TotalExpense, TotalProfit

Examples

Daily order count for the last 30 days

query {
  orderTimeBuckets(
    organizationId: 1
    interval: Day1
    dateField: "created"
    start: "2026-02-21T00:00:00Z"
    end: "2026-03-23T00:00:00Z"
  ) {
    totalCount
    buckets {
      bucketStart
      count
    }
  }
}

Weekly revenue breakdown with filter

query {
  orderTimeBuckets(
    organizationId: 1
    interval: Week1
    dateField: "created"
    start: "2026-01-01T00:00:00Z"
    end: "2026-03-23T00:00:00Z"
    filter: "orderStatus.name:Completed"
  ) {
    buckets {
      bucketStart
      bucketEnd
      count
      summary {
        totalIncome
        totalExpense
        totalProfit
      }
    }
  }
}

Hourly analysis with drill-down to orders

query {
  orderTimeBuckets(
    organizationId: 1
    interval: Hour1
    dateField: "customValues.ETA"
    start: "2026-03-22T00:00:00Z"
    end: "2026-03-23T00:00:00Z"
  ) {
    buckets {
      bucketStart
      count
      orders(take: 5, orderBy: "created desc") {
        items {
          orderId
          trackingNumber
          customValues
        }
        totalCount
      }
    }
  }
}

Related

• GraphQL Overview
• Filtering