Query Data Skill

1. Naming Conventions

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

• Namespace: app__ prefix (snake_case).
• Tables: appplural (List), appsingular (By ID).
• Mutations: insert..., update..., delete_....

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

• Query List: comacmecrm__users
• Query Single: comacmecrm__user

2. Reading Data (Query)

Basic List

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)

Aggregations (Stats)

Fetch counts, sums, averages.

• agg Suffix: Use tablename_agg.
• aggregate: Holds the stats.
• nodes: Holds the actual records (optional).

query UserStats {
  com_acme_crm__users_agg(where: { status: { _eq: "active" } }) {
    aggregate {
      count
      sum { lifetime_value }
      avg { age }
    }
  }
}

3. Modifying Data (Mutation)

Insert

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

Update (Patch)

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

Delete

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).

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).

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.

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