query（查询工具）

Crystallize Query Skill

Query product data, content, and commerce information from Crystallize using GraphQL APIs. This skill covers reading data for storefronts, admin interfaces, product pages, search, and cart operations.

Consultation Approach

Before writing queries, understand the context. Ask clarifying questions:

1. What data do you need? Products, orders, customers, content, shapes?
2. Is this for a storefront or admin interface? Discovery/Catalogue for storefronts, Core for admin.
3. Do you need search/filtering or exact path reads? Discovery for search and faceted navigation, Catalogue for deterministic reads by path.
4. Do you have authentication configured? Core API requires access tokens. Discovery/Catalogue can be open but should be secured in production.
5. What volume of results? Pagination strategy matters — cursor-based is recommended for all APIs.

Choosing the Right API

• Need search, filtering, or faceting? → Discovery API
• Know the exact path? Need strong consistency? → Catalogue API
• Admin interface? Orders, customers, shapes? → Core API
• Cart/checkout operations? → Shop API

How It Works

Crystallize provides four main APIs for querying data:

1. Core API - Full read/write API with advanced filtering. Best for admin interfaces, customer/order management.
2. Discovery API - Semantic API for search, browse, filter, and faceting. Best for storefronts.
3. Catalogue API - Path-based reads for deterministic data access.
4. Shop API - Cart and checkout queries at the edge.

API Endpoints

Usage

Core API (Admin & Advanced Queries)

The Core API provides full read/write access with advanced filtering capabilities:

• Read items by ID with full component data
• List items with pagination and filtering
• Query customers and orders with complex filters
• Filter orders by customer, SKU, payment provider, metadata
• Access shape and piece definitions
• Manage flows and archives

# Example: Get item with components
query GetItem {
    item(id: "item-id", language: "en") {
        ... on Product {
            id
            name
            components {
                componentId
                content
            }
            defaultVariant {
                sku
                price
                stock
            }
        }
    }
}

# Example: List orders filtered by customer
query ListOrders {
    orders(
        tenantId: "tenant-id"
        first: 20
        filter: { customerIdentifier: "customer@example.com" }
        sort: { field: createdAt, direction: desc }
    ) {
        edges {
            node {
                id
                total {
                    gross
                    currency
                }
                customer {
                    identifier
                }
            }
        }
    }
}

See Core API Queries Reference for complete documentation.

Discovery API (Recommended for Storefronts)

The Discovery API is the primary API for frontend development. It supports:

• Full-text search
• Filtering by any component or attribute
• Faceted navigation
• Sorting and cursor-based pagination

The Discovery API has two entry points: search for full-text queries with facets, and browse for shape-typed access where each shape becomes its own query type.

Note: The Discovery API uses lowercase type names in inline fragments (... on product, ... on category) because types are derived from your shape identifiers. You can still use it for interface (... on Product, ... on Folder).

# Example: Browse products by shape with pagination
{
    browse {
        product(language: en, pagination: { limit: 25 }) {
            summary {
                totalHits
                hasMoreHits
                endCursor
            }
            hits {
                name
                path
                ... on Product {
                    defaultVariant {
                        sku
                        defaultPrice
                        firstImage {
                            url
                        }
                    }
                }
            }
        }
    }
}

# Example: Search with facets and filtering
{
    search(
        language: en
        term: "green"
        filters: { type_in: [product] }
        facets: { shape: { limit: 5 } }
        pagination: { limit: 20 }
    ) {
        summary {
            totalHits
            hasMoreHits
            endCursor
            facets
        }
        hits {
            name
            path
            ... on product {
                defaultVariant {
                    defaultPrice
                }
            }
        }
    }
}

Catalogue API (Path-Based Reads)

Use for deterministic reads when you know the exact path:

{
    catalogue(language: "en", path: "/shop/plants") {
        name
        ... on Product {
            variants {
                sku
                name
                price
            }
        }
    }
}

Shop API Queries

Retrieve cart and order intent data:

query {
    cart(id: "cart-id") {
        id
        items {
            sku
            name
            quantity
            price {
                gross
                net
            }
        }
        total {
            gross
            net
        }
    }
}

Best Practices

1. Choose the right API - Core for admin, Discovery for storefront search, Catalogue for path-based reads
2. Use Discovery API for storefronts - It's optimized for performance and supports search/filter
3. Include deterministic sorting - Always add a secondary sort field (like itemId) for stable pagination
4. Request only needed fields - GraphQL allows precise field selection to minimize payload
5. Handle async updates - Discovery API may have sub-second delay for recently published content
6. Protect APIs in production - Configure authentication for sensitive data
7. Use Core API for complex filters - Only Core API supports filtering orders by customer, SKU, payment provider

References

• Core API Queries Reference - Items, customers, orders, shapes with advanced filtering
• Discovery API Reference - Detailed search, filter, and faceting documentation
• Catalogue API Reference - Path-based query documentation
• Shop API Queries Reference - Cart and checkout query documentation (/cart endpoint)
• Shop API Order Queries Reference - Order queries by ID or customer (/order endpoint)