Filtering and Sorting

The Kojo API offers several options for sorting and filtering data.

These parameters are often used in combination with pagination.

Sorting

Records may be sorted using the orderBy and direction parameters. The Kojo API supports sorting for every field that is a string, numeric, or datetime type.

When using pagination, sorting will be done across all records in the database, prior to paginating the records.

Example Query

query {
  jobs(
    orderBy: code,
    direction: ASC
  ) {
    id
    code
    name
  }
}

Querying With Filters

Queries that return an array of entities can be filtered by various parameters within the queried data. The specific fields that support filtering are listed under the Parameters heading of each query that returns an array of data.

Filters are applied by combining a field name with the specific type of filter that is to be used. The datatype of the field determines which filters are available for the field.

For GraphQL filters, append the filter type to the end of the field name with an underscore. For example, the query below returns all orders with a purchaseOrderNumber that starts with "1-":

query {
  orders(
    filter: { purchaseOrderNumber_starts_with: "1-" }
  ) {
    id
    purchaseOrderNumber
  }
}

For REST filters, filters are defined in query params. For example, the query below returns all orders with a purchaseOrderNumber that begins with "1-":

GET https://api.kojo.tech/orders?filter.purchaseOrderNumber_starts_with=1-

Multiple filters can be used simultaneously. See the examples below.

query {
  orders(
    filter: { 
        purchaseOrderNumber_starts_with: "1",
        createdAt_lt: "2024-01-01T10:00:00.000Z"
    }
  ) {
    id
    createdAt
    purchaseOrderNumber
  }
}

GET https://api.kojo.tech/orders?filter.purchaseOrderNumber_starts_with=1&filter.createdAt_lt=2024-01-01T10:00:00.000Z

Available Filtering Parameters

The available filtering parameters depend on the datatype of the field defined in the filter.

String Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
<field name>	Field is equal to the provided string	String	code: "100"	?filter.code=100
not	Field is not equal to the provided string	String	code_not: "100"	?filter.code_not=100
in	Field matches a value in the provided array	String[]	code_in: ["100", "200"]	?filter[integrationState_in]=ERROR&filter[integrationState_in]=LINKED OR ?&filter.integrationState_in=LINKING&filter.integrationState_in=LINKED
not_in	Field does not match a value in the provided array	String[]	code_not_in: ["100", "200"]	N/A
contains	Field contains the provided string	String	code_contains: "10"	?filter.code_contains=10
not_contains	Field does not contain the provided string	String	code_not_contains: "10"	?filter.code_not_contains=10
starts_with	Field starts with the provided string	String	code_starts_with: "10"	?filter.code_starts_with=10
not_starts_with	Field does not start with the provided string	String	code_not_starts_with: "10"	?filter.code_not_starts_with=10
ends_with	Field ends with the provided string	String	code_ends_with: "10"	?filter.code_ends_with=10
not_ends_with	Field does not end with the provided string	String	code_not_ends_with: "10"	?filter.code_not_ends_with=10

Float/Int Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
<field name>	Field is equal to the provided number	number	extPrice: 25	?filter.extPrice=25
gt	Field is greater than the provided number	number	extPrice_gt: 25	?filter.extPrice_gt=25
gte	Field is greater than or equal to the provided number	number	extPrice_gte: 25	?filter.extPrice_gte=25
lt	Field is less than the provided number	number	extPrice_lt: 25	?filter.extPrice_lt=25
lte	Field is less than or equal to the provided number	number	extPrice_lte: 25	?filter.extPrice_lte=25

Boolean Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
<field name>	Field is equal to the provided boolean	number	taxExempt: true	?filter.taxExempt=true
not	Field is the inverse of the provided boolean	boolean	taxExempt_not: true	?filter.taxExempt_not=true

ID Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
id	ID is equal to the provided ID	ID	id: "clqzdedh90012b24xndju75yu"	?filter.id=clqzdedh90012b24xndju75yu
in	ID matches a value in the provided array	ID[]	id_in: ["clqzdedh90012b24xndju75yu", "clpkd1sgv0000uy4xzw6r90wi"]	N/A
not_in	ID does not match a value in the provided array	ID[]	id_not_in: ["clqzdedh90012b24xndju75yu", "clpkd1sgv0000uy4xzw6r90wi"]	N/A

Enum/Scalar Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
<field name>	Field is equal to the provided enum value	Enum	state: DRAFT	?filter.state=DRAFT
not	Field is not equal to the provided enum value	Enum	state_not: DRAFT	?filter.state_not=DRAFT
in	Field is equal to a value in the provided array of enums	Enum[]	state_in: [ACTIVE, DRAFT]	N/A
not_in	Field is not equal to a value in the provided array of enums	Enum[]	state_not_in: [ACTIVE, DRAFT]	N/A

DateTime Field Filters

Filter String	Description	Expected Input	GraphQL Example	REST Example
gt	Date field is after the provided date	DateTime	updatedAt_gt: "2024-01-25T15:30:00"	?filter.updatedAt_gt=2024-01-25T15:30:00
gte	Date field is after or equal to the provided date	DateTime	updatedAt_gte: "2024-01-25T15:30:00"	?filter.updatedAt_gte=2024-01-25T15:30:00
lt	Date field is before the provided date	DateTime	updatedAt_lt: "2024-01-25T15:30:00"	?filter.updatedAt_lt=2024-01-25T15:30:00
lte	Field is less than or equal to the provided number	DateTime	updatedAt_lte: "2024-01-25T15:30:00"	?filter.updatedAt_lte=2024-01-25T15:30:00

When providing DateTime arguments to a filter, any of the following formats are accepted:

• 2024-01-25
• 2024-01-25T15:30:00
• 2024-01-25T15:30:00.500
• 2024-01-25T15:30:00.500Z
• 2024-01-25T15:30:00.500-0400

Retrieving Records Based on Timestamp

When integrating Kojo with another system, you may want to only get records that have been modified since your last sync. You can do this through the Kojo API by using the updatedAfter parameter. When using this parameter, Kojo will only return records that were created or updated after the specified time.

The updatedAfter parameter should be a UTC timestamp in the accepted date format. If the updatedAfter parameter is not provided, Kojo will return all records regardless of when they were last modified.