Where Inputs

Input types for filtering objects in GraphQL queries, providing comprehensive filtering capabilities across all pyck entities.

Audience: Programmer

WhereInput types are GraphQL input types used for filtering objects in queries. They provide a comprehensive set of predicates for filtering entities based on various criteria, including field comparisons, logical operations, and relationship filtering.

Common Structure

All WhereInput types in pyck follow a consistent structure with the following components:

Logical Operators

Every WhereInput type includes these logical operators:

Field	Type	Description
not	<Type>WhereInput	Negates the provided conditions
and	[<Type>WhereInput!]	All conditions must match (logical AND)
or	[<Type>WhereInput!]	At least one condition must match (logical OR)

Field Predicates

For each field in the entity, WhereInput provides various comparison operators:

Basic Comparisons

• field: Equal to value

• fieldNEQ: Not equal to value

• fieldIn: Value is in the provided list

• fieldNotIn: Value is not in the provided list

Ordering Comparisons

• fieldGT: Greater than value

• fieldGTE: Greater than or equal to value

• fieldLT: Less than value

• fieldLTE: Less than or equal to value

String-Specific Operations

• fieldContains: String contains substring

• fieldHasPrefix: String starts with prefix

• fieldHasSuffix: String ends with suffix

• fieldEqualFold: Case-insensitive equality

• fieldContainsFold: Case-insensitive contains

Null Checks

• fieldIsNil: Field is null

• fieldNotNil: Field is not null

Relationship Filtering

For entities with relationships, WhereInput types provide:

• hasRelationship: Boolean indicating if the relationship exists

• hasRelationshipWith: Array of related entity WhereInput for complex filtering

Data Field Operations

For entities with JSON data fields, pyck provides powerful query operations:

• Data: Match exact value at JSON path - Data: ["path", "value"]

• DataHasKey: Check if key exists at path - DataHasKey: "path"

• DataIn: Value at path is in list - DataIn: ["path", "value1", "value2"]

• DataContains: String at path contains substring - DataContains: ["path", "substring"]

Note: Data field operations are available for most WhereInput types but not for WorkflowSignalWhereInput.

Example: Find customers with name "Max" in their data field:

query {
  customers(where: {
    Data: ["name", "Max"]
  }) {
    edges {
      node {
        id
        data
      }
    }
  }
}

For comprehensive JSON field query documentation, see JSON Field Queries.

Available WhereInput Types

The following WhereInput types are available in the pyck GraphQL API:

Type	Description
AttachmentWhereInput	Filtering for file attachments
CompanyWhereInput	Filtering for company entities
CustomerWhereInput	Filtering for customer records
DataTypeWhereInput	Filtering for data type definitions
EventWhereInput	Filtering for system events
InventoryCollectionWhereInput	Filtering for inventory collections
InventoryItemSetWhereInput	Filtering for inventory item sets
InventoryItemWhereInput	Filtering for inventory items
ItemMovementWhereInput	Filtering for item movements
PickingOrderItemWhereInput	Filtering for picking order items
PickingOrderWhereInput	Filtering for picking orders
ReceivingInboundItemWhereInput	Filtering for receiving inbound items
ReceivingInboundWhereInput	Filtering for receiving inbound records
RepositoryMovementWhereInput	Filtering for repository movements
RepositoryWhereInput	Filtering for repository/location records
StockWhereInput	Filtering for stock records
SupplierWhereInput	Filtering for supplier records
TransactionWhereInput	Filtering for transaction records
UserWhereInput	Filtering for user accounts
WorkflowSignalWhereInput	Filtering for workflow signals
WorkflowWhereInput	Filtering for workflow records

Usage Examples

Basic Filtering

query {
  inventoryItems(
    where: {
      sku: "PHONE-001"
    }
  ) {
    edges {
      node {
        id
        sku
        data
      }
    }
  }
}

Logical Operations

query {
  inventoryItems(
    where: {
      and: [
        { skuContainsFold: "PHONE" },
        { createdAtGTE: "2023-05-01T00:00:00Z" }
      ]
    }
  ) {
    edges {
      node {
        id
        sku
        createdAt
      }
    }
  }
}

Complex Filtering with OR

query {
  inventoryItems(
    where: {
      or: [
        { skuContains: "PHONE" },
        { skuContains: "TABLET" }
      ]
    }
  ) {
    edges {
      node {
        id
        sku
      }
    }
  }
}

Negation

query {
  inventoryItems(
    where: {
      not: {
        skuContains: "DISCONTINUED"
      }
    }
  ) {
    edges {
      node {
        id
        sku
      }
    }
  }
}

Relationship Filtering

query {
  inventoryItems(
    where: {
      hasItemstockWith: [
        {
          and: [
            { quantityGT: 0 },
            { repositoryID: "warehouse-main" }
          ]
        }
      ]
    }
  ) {
    edges {
      node {
        id
        sku
        itemstock {
          quantity
          repositoryID
        }
      }
    }
  }
}

Data Field Filtering

query {
  inventoryItems(
    where: {
      and: [
        { Data: ["color", "size"] },
        { DataContains: ["red", "large"] }
      ]
    }
  ) {
    edges {
      node {
        id
        sku
        data
      }
    }
  }
}

String Filtering

query {
  customers(
    where: {
      and: [
        { nameHasPrefix: "Acme" },
        { emailContainsFold: "@company.com" }
      ]
    }
  ) {
    edges {
      node {
        id
        name
        email
      }
    }
  }
}

Date Range Filtering

query {
  transactions(
    where: {
      and: [
        { createdAtGTE: "2023-01-01T00:00:00Z" },
        { createdAtLT: "2023-02-01T00:00:00Z" }
      ]
    }
  ) {
    edges {
      node {
        id
        createdAt
        type
      }
    }
  }
}

Null Checks

query {
  inventoryItems(
    where: {
      and: [
        { dataTypeIDNotNil: true },
        { descriptionIsNil: false }
      ]
    }
  ) {
    edges {
      node {
        id
        sku
        dataTypeID
        description
      }
    }
  }
}

JavaScript Usage

When using the GraphQL API from JavaScript, WhereInput objects can be constructed as regular objects:

const whereInput = {
  and: [
    { skuContainsFold: searchTerm },
    { createdAtGTE: startDate.toISOString() },
    {
      hasItemstockWith: [
        { quantityGT: 0 }
      ]
    }
  ]
};

const query = `
  query GetFilteredItems($where: InventoryItemWhereInput) {
    inventoryItems(where: $where) {
      edges {
        node {
          id
          sku
          createdAt
        }
      }
    }
  }
`;

const result = await client.query({
  query,
  variables: { where: whereInput }
});

Best Practices

1. Use specific field predicates: Instead of loading all data and filtering client-side, use WhereInput to filter at the database level for better performance.

2. Combine logical operators: Use and, or, and not to create complex filtering conditions that match your business logic.

3. Leverage relationship filtering: Use has...With predicates to filter based on related entity properties without separate queries.

4. Case-insensitive searching: Use *EqualFold and *ContainsFold predicates for user-friendly search functionality.

5. Date range queries: Combine *GTE and *LT predicates for effective date range filtering.

6. Null safety: Use *IsNil and *NotNil predicates to handle optional fields properly.

7. Index-friendly queries: Structure your where conditions to leverage database indexes for optimal performance.

RepositoryWhereInput Breaking Changes

The RepositoryWhereInput type has been updated with the following breaking changes:

Removed Fields

The following parentID comparison filters have been removed because parentID is now an edge reference (ID type) instead of a UUID:

• parentIDGT - Greater than comparison (removed)

• parentIDGTE - Greater than or equal comparison (removed)

• parentIDLT - Less than comparison (removed)

• parentIDLTE - Less than or equal comparison (removed)

Changed Fields

The following parentID fields now use ID type instead of UUID:

Field	Old Type	New Type
parentID	UUID	ID
parentIDNEQ	UUID	ID
parentIDIn	[UUID!]	[ID!]
parentIDNotIn	[UUID!]	[ID!]

New Edge Predicates

New edge predicates have been added for filtering repositories based on parent/child relationships:

Field	Type	Description
hasParent	Boolean	Filter repositories that have (or don't have) a parent
hasParentWith	[RepositoryWhereInput!]	Filter repositories whose parent matches the given conditions
hasChildren	Boolean	Filter repositories that have (or don't have) children
hasChildrenWith	[RepositoryWhereInput!]	Filter repositories whose children match the given conditions

Migration Examples

Before (finding root repositories):

query {
  repositories(where: { parentIDIsNil: true }) {
    edges { node { id name } }
  }
}

After (finding root repositories):

query {
  repositories(where: { hasParent: false }) {
    edges { node { id name } }
  }
}

Before (filtering by parent):

query {
  repositories(where: { parentID: "uuid-here" }) {
    edges { node { id name } }
  }
}

After (filtering by parent with conditions):

query {
  repositories(
    where: {
      hasParentWith: [{ name: "Main Warehouse" }]
    }
  ) {
    edges { node { id name } }
  }
}

Finding repositories with children:

query {
  repositories(
    where: {
      hasChildren: true,
      hasChildrenWith: [{ type: static }]
    }
  ) {
    edges {
      node {
        id
        name
        children { id name }
      }
    }
  }
}

Related Documentation

• InventoryItemWhereInput - Detailed documentation for inventory item filtering

• GraphQL Queries - How to use WhereInput in various queries

• Error Handling - Common errors when using WhereInput types

• Repository Type - Repository type documentation with parent/children edges