OrderBy Inputs

OrderByInput types for sorting GraphQL query results

Audience: Programmer

OrderByInput types define how query results should be sorted in the pyck GraphQL API. They provide a standardized way to order results by various fields in ascending or descending order.

Common Structure

All OrderByInput types follow a consistent pattern:

input EntityOrder {
  field: EntityOrderField
  direction: OrderDirection! = ASC
  jsonPath: String
  jsonType: JSONType
}

Where:

• field: An enum specifying which field to sort by (optional when using JSONB ordering)

• direction: Either ASC (ascending) or DESC (descending)

• jsonPath: Dot-notation path into a JSONB column (e.g., "meta.weight") for ordering by nested JSON values

• jsonType: Type casting for the extracted JSONB value (NUMBER, STRING, or BOOLEAN)

Usage Examples

Basic Sorting

Sort inventory items by name in ascending order:

query {
  inventoryItems(orderBy: { field: NAME, direction: ASC }) {
    edges {
      node {
        id
        name
        sku
      }
    }
  }
}

Descending Order

Sort picking orders by creation date (newest first):

query {
  pickingOrders(orderBy: { field: CREATED_AT, direction: DESC }) {
    edges {
      node {
        id
        referenceId
        createdAt
      }
    }
  }
}

JavaScript Example

const result = await client.query({
  query: gql`
    query GetCustomers($orderBy: CustomerOrder) {
      customers(orderBy: $orderBy) {
        edges {
          node {
            id
            data
          }
        }
      }
    }
  `,
  variables: {
    orderBy: {
      field: 'TENANT_ID',
      direction: 'ASC'
    }
  }
});

Available Order Types

The following Order input types are available in pyck:

Input Type	Used For	Common Sort Fields
CustomerOrder	Customers	TENANT_ID, CREATED_AT, CREATED_BY
DataTypeOrder	Data type definitions	NAME, SLUG, CREATED_AT
EventOrder	Event definitions	NAME, TOPIC, CREATED_AT
FileOrder	File attachments	NAME, SIZE, CREATED_AT
GroupOrder	User groups	NAME, CREATED_AT
InventoryCollectionOrder	Inventory collections	HANDLER, CREATED_AT
InventoryItemOrder	Inventory items	SKU, CREATED_AT
InventoryItemSetOrder	Item sets	SKU, CREATED_AT
ItemMovementOrder	Item movements	CREATED_AT, EXECUTED_AT
KeyValueOrder	Key-value pairs	NAME, CREATED_AT
PickingOrderOrder	Picking orders	CUSTOMER_ID, CREATED_AT
PickingOrderItemOrder	Picking order items	SKU, QUANTITY, CREATED_AT
ReceivingInboundOrder	Receiving inbounds	ORDER_ID, SUPPLIER_ID, CREATED_AT
ReceivingInboundItemOrder	Inbound items	SKU, QUANTITY, CREATED_AT
RepositoryOrder	Repositories	NAME, TYPE, CREATED_AT
RepositoryMovementOrder	Repository movements	CREATED_AT, EXECUTED_AT
RoleOrder	User roles	NAME, CREATED_AT
StockOrder	Stock levels	CREATED_AT, QUANTITY
SupplierOrder	Suppliers	TENANT_ID, CREATED_AT
TenantOrder	Tenants	NAME, CREATED_AT
TransactionOrder	Transactions	TYPE, CREATED_AT
UserOrder	Users	USERNAME, EMAIL, CREATED_AT
WorkflowOrder	Workflows	NAME, ACTIVE, CREATED_AT
WorkflowSignalOrder	Workflow signals	EVENT_NAME, CREATED_AT

Order Field Enums

Each entity has its own OrderField enum defining sortable fields. Common fields include:

• NAME - Entity name

• CREATED_AT - Creation timestamp

• UPDATED_AT - Last update timestamp

• REFERENCE_ID - External reference identifier

• SKU - Stock keeping unit

• EMAIL - Email address

• TYPE - Entity type

• EXECUTED_AT - Execution timestamp

JSONB Column Ordering

All OrderByInput types support ordering by nested fields within JSONB columns (such as the data field on entities). This allows you to sort by custom attributes stored as JSON.

Structure

When ordering by JSONB fields, you must provide:

• jsonPath: Dot-notation path to the nested field (e.g., "attributes.weight", "meta.priority")

• jsonType: The data type of the value for proper sorting (NUMBER, STRING, or BOOLEAN)

• direction: Sort direction (ASC or DESC)

• field: Can be omitted when using JSONB ordering

Example: Order Inventory Items by Weight

query {
  inventoryItems(
    orderBy: {
      direction: DESC,
      jsonPath: "attributes.weight",
      jsonType: NUMBER
    }
  ) {
    edges {
      node {
        id
        sku
        data
      }
    }
  }
}

Example: Order by Nested String Field

query {
  customers(
    orderBy: {
      direction: ASC,
      jsonPath: "company.name",
      jsonType: STRING
    }
  ) {
    edges {
      node {
        id
        data
      }
    }
  }
}

Example: Order by Boolean Flag

query {
  inventoryItems(
    orderBy: {
      direction: DESC,
      jsonPath: "flags.isPriority",
      jsonType: BOOLEAN
    }
  ) {
    edges {
      node {
        id
        sku
        data
      }
    }
  }
}

JSONType Enum

The JSONType enum specifies how to cast the extracted JSONB value for sorting:

enum JSONType {
  NUMBER   # Cast to numeric for number comparisons
  STRING   # Cast to text for string comparisons
  BOOLEAN  # Cast to boolean for boolean comparisons
}

JSONB Ordering Notes

1. Type Casting: Always specify the correct jsonType to ensure proper sorting behavior

2. Missing Fields: Items without the specified JSON path will be sorted as null values

3. Nested Paths: Use dot notation for deeply nested fields (e.g., "meta.shipping.weight")

4. Performance: JSONB ordering may be slower than ordering by indexed columns

Best Practices

1. Default Sorting: Consider providing a default sort order when none is specified

2. Performance: Be aware that sorting by non-indexed fields may impact query performance

3. JSONB Performance: JSONB ordering is more expensive than standard field ordering; use judiciously

4. Consistency: Use consistent sorting across related queries for better UX

5. Null Values: Understand how null values are sorted (typically first for ASC, last for DESC)

6. Type Safety: Always specify the correct jsonType when using JSONB ordering to avoid unexpected results

Combining with Pagination

OrderByInput works seamlessly with cursor-based pagination:

query {
  inventoryItems(
    first: 10,
    after: "cursor123",
    orderBy: { field: CREATED_AT, direction: DESC }
  ) {
    edges {
      node {
        id
        name
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

See Also

• WhereInput Types for filtering

• Pagination for cursor-based pagination

• OrderDirection Enum for sort directions