Mutation Inputs

CreateInput and UpdateInput types for GraphQL mutations

Audience: Programmer

CreateInput and UpdateInput types define the structure of data accepted by create and update mutations in the pyck GraphQL API. These input types ensure type safety and validation when modifying data.

Naming Patterns

pyck follows consistent naming patterns for mutation inputs:

• Create: Create[Entity]Input (e.g., CreateInventoryItemInput)

• Update: Update[Entity]Input (e.g., UpdateInventoryItemInput)

CreateInput Types

CreateInput types define required and optional fields when creating new entities.

Common Structure

input CreateEntityInput {
  # Required fields
  name: String!
  type: EntityType!
  
  # Optional fields
  description: String
  data: Map
  
  # Relationships
  parentId: ID
  categoryIds: [ID!]
}

Example: Creating an Inventory Item

mutation {
  createInventoryItem(input: {
    name: "Blue Widget",
    sku: "WIDGET-BLUE-001",
    description: "A high-quality blue widget",
    data: {
      color: "blue",
      weight: 150,
      dimensions: {
        length: 10,
        width: 5,
        height: 3
      }
    }
  }) {
    id
    name
    sku
    data
  }
}

UpdateInput Types

UpdateInput types define which fields can be modified when updating existing entities. All fields are typically optional, allowing partial updates.

Common Structure

input UpdateEntityInput {
  # All fields are optional for partial updates
  name: String
  description: String
  status: EntityStatus
  data: Map
  
  # Clear values by setting to null
  description: String  # null clears the description
  
  # Relationship updates
  parentId: ID
  addCategoryIds: [ID!]
  removeCategoryIds: [ID!]
}

Example: Updating an Inventory Item

mutation {
  updateInventoryItem(id: "inv_123", input: {
    name: "Blue Widget - Premium",
    data: {
      color: "blue",
      weight: 155,
      premium: true
    }
  }) {
    id
    name
    data
    updatedAt
  }
}

Available Input Types

Inventory Management

Create Input	Update Input	Used For
CreateInventoryItemInput	UpdateInventoryItemInput	Products and items
CreateRepositoryInput	UpdateRepositoryInput	Storage locations
CreateItemMovementInput	UpdateItemMovementInput	Item movements
CreateRepositoryMovementInput	UpdateRepositoryMovementInput	Bulk movements
CreateCollectionMovementInput	UpdateInventoryCollectionInput	Collection movements
CreateInventoryItemSetInput	UpdateInventoryItemSetInput	Item groupings

Order Management

Create Input	Update Input	Used For
CreatePickingOrderInput	UpdatePickingOrderInput	Picking orders
CreatePickingOrderItemInput	UpdatePickingOrderItemInput	Order line items
CreateReceivingInboundInput	UpdateReceivingInboundInput	Inbound shipments
CreateReceivingInboundItemInput	UpdateReceivingInboundItemInput	Inbound items

Master Data

Create Input	Update Input	Used For
CreateCustomerInput	UpdateCustomerInput	Customer records
CreateSupplierInput	UpdateSupplierInput	Supplier records
CreateDataTypeInput	UpdateDataTypeInput	JSON schema definitions

System Configuration

Create Input	Update Input	Used For
CreateFileInput	UpdateFileInput	File attachments
CreateWorkflowInput	UpdateWorkflowInput	Workflow definitions
CreateWorkflowSignalInput	UpdateWorkflowSignalInput	Workflow triggers

Common Fields

Data Field

Most entities support a flexible data field of type Map for custom attributes:

input CreateInventoryItemInput {
  # ... standard fields ...
  data: Map  # Stores custom JSON data
}

Timestamps

Create/Update timestamps are automatically managed:

• createdAt: Set automatically on creation

• updatedAt: Updated automatically on modification

Relationships

Input types handle relationships through ID references:

input CreatePickingOrderItemInput {
  pickingOrderId: ID!    # Parent relationship
  inventoryItemId: ID!   # Item reference
  quantity: Int!
}

Best Practices

1. Partial Updates

Only include fields you want to change in update mutations:

// Good - Only updates specific fields
const updateInput = {
  name: "New Name",
  status: "ACTIVE"
};

// Avoid - Sending unchanged fields
const updateInput = {
  name: "New Name",
  description: existingDescription,  // Unnecessary
  status: "ACTIVE",
  type: existingType  // Unnecessary
};

2. Null Handling

Use null to explicitly clear optional fields:

mutation {
  updateCustomer(id: "cust_123", input: {
    email: "[email protected]",
    phone: null  # Clears the phone number
  }) {
    id
    email
    phone
  }
}

3. Data Field Validation

The data field is validated against DataType schemas:

// First, create a DataType for validation
const dataType = await createDataType({
  name: "ProductAttributes",
  schema: {
    type: "object",
    properties: {
      color: { type: "string" },
      weight: { type: "number", minimum: 0 }
    },
    required: ["color"]
  }
});

// Then use it when creating items
const item = await createInventoryItem({
  name: "Widget",
  sku: "W-001",
  dataTypeId: dataType.id,
  data: {
    color: "blue",  // Required by schema
    weight: 150     // Validated as positive number
  }
});

4. Batch Operations

For bulk updates, consider using specialized batch mutations when available:

mutation {
  updateInventoryItems(
    where: { sku: { hasPrefix: "WIDGET-" } },
    input: { status: "DISCONTINUED" }
  ) {
    count
    items {
      id
      sku
      status
    }
  }
}

JavaScript Example

// Create a new inventory item
const createItem = async (itemData) => {
  const result = await client.mutate({
    mutation: gql`
      mutation CreateItem($input: CreateInventoryItemInput!) {
        createInventoryItem(input: $input) {
          id
          name
          sku
          data
          createdAt
        }
      }
    `,
    variables: {
      input: {
        name: itemData.name,
        sku: itemData.sku,
        description: itemData.description,
        data: itemData.customAttributes
      }
    }
  });
  
  return result.data.createInventoryItem;
};

// Update an existing item
const updateItem = async (itemId, updates) => {
  const result = await client.mutate({
    mutation: gql`
      mutation UpdateItem($id: ID!, $input: UpdateInventoryItemInput!) {
        updateInventoryItem(id: $id, input: $input) {
          id
          name
          sku
          data
          updatedAt
        }
      }
    `,
    variables: {
      id: itemId,
      input: updates  // Only include fields to update
    }
  });
  
  return result.data.updateInventoryItem;
};

See Also

• Individual mutation documentation for specific input requirements

• WhereInput Types for filtering in batch operations

• Data Types for data field validation

• Error Handling for validation error responses