AgentSkillsCN

query-data

精通自动生成的 GraphQL API（查询、变更、聚合）的专家指南。

SKILL.md
--- frontmatter
name: query-data
description: Expert guide to the auto-generated GraphQL API (Queries, Mutations, Aggregations).

Query Data Skill

1. Naming Conventions

The Platform auto-generates GraphQL fields from your SCL schema.

  • •Namespace: app__ prefix (snake_case).
  • •Tables: app__plural (List), app__singular (By ID).
  • •Mutations: insert_..., update_..., delete_....

Example: App com.acme.crm (com_acme_crm), Table user (users).

  • •Query List: com_acme_crm__users
  • •Query Single: com_acme_crm__user

2. Reading Data (Query)

Basic List

graphql
query ListUsers {
  users: com_acme_crm__users(
    limit: 10
    offset: 0
    order_by: { created_at: desc }
  ) {
    id
    email
    # Nested relationship
    orders {
      id
      total
    }
  }
}

Filtering (where)

OperatorLogicExample
_eq, _neqEquals / Not Equals{ status: { _eq: "active" } }
_gt, _ltGreater / Less Than{ count: { _gt: 5 } }
_in, _ninIn List{ id: { _in: ["A", "B"] } }
_is_nullIs Null{ notes: { _is_null: true } }
_and, _orLogic Groups{ _or: [ { a: ... }, { b: ... } ] }

Aggregations (Stats)

Fetch counts, sums, averages.

  • •_agg Suffix: Use table_name_agg.
  • •aggregate: Holds the stats.
  • •nodes: Holds the actual records (optional).
graphql
query UserStats {
  com_acme_crm__users_agg(where: { status: { _eq: "active" } }) {
    aggregate {
      count
      sum { lifetime_value }
      avg { age }
    }
  }
}

3. Modifying Data (Mutation)

Insert

graphql
mutation NewUser($data: JSON!) {
  # returns the created object
  insert_com_acme_crm__user(object: $data) {
    id
  }
}

Update (Patch)

graphql
mutation MakeActive($id: ID!) {
  update_com_acme_crm__user(
    id: $id
    _set: { status: "active", updated_at: "now()" }
  ) {
    id
    status
  }
}

Delete

graphql
mutation RemoveUser($id: ID!) {
  delete_com_acme_crm__user(id: $id) {
    id
  }
}

4. Advanced Querying (Aggregation + Nodes)

Mixed Pagination

Get the TOTAL count of matches (aggregate) but only fetch the FIRST PAGE of actual data (nodes).

graphql
query SearchAndPaginate {
  com_acme_crm__users_agg(
    where: { status: { _eq: "active" } }
    order_by: { created_at: desc }
    limit: 20  # Applies to 'nodes'
    offset: 0  # Applies to 'nodes'
  ) {
    # 1. Total count matching the filter (ignoring limit!)
    aggregate {
      count
    }
    # 2. The actual page of data (respected limit)
    nodes {
      id
      email
    }
  }
}

Nested Aggregation

Calculate stats for related records (e.g., Average Order Value per User).

graphql
query UserStats {
  users: com_acme_crm__users {
    email
    # Aggregate on relationship
    orders_agg {
      aggregate {
        count
        sum { total }
      }
    }
  }
}

5. Introspection

When in doubt, query the schema itself to discover available types and fields.

graphql
query Introspection {
  __schema {
    types { name kind }
  }
}