Aggregations And Functions

Aggregate fields

GraphJin exposes aggregate fields by prefixing a column with the aggregate name.

query {
  products(where: { id: { lteq: 100 } }) {
    count_id
    min_price
    max_price
    avg_price
  }
}

If a select contains only aggregates and no distinct, GraphJin returns a single global aggregate row instead of a page of per-row aggregate values.

Grouped summaries

Use distinct to group by one or more columns, then request aggregate fields for each group.

query {
  products(
    distinct: [country_code]
    where: { id: { lteq: 100 } }
    order_by: { count_id: desc }
  ) {
    country: country_code
    count_id
    avg_price
  }
}

Grouped queries still follow SQL grouping rules. If a nested join would require a non-grouped foreign key, GraphJin should reject the ambiguous shape instead of emitting broken SQL; root the query at the dimension table when you need a nested object per group.

Expression aggregates

Expression aggregates calculate metrics in the database, not in client code.

query {
  products(where: { id: { lteq: 100 } }) {
    doubled: sum(expr: { mul: [id, 2] })
  }
}

Expressions support arithmetic operators such as add, sub, mul, div, mod, literal values, column references, casts, coalesce, nullif, and case expressions.

Ratio-of-aggregates uses a bare expression field whose nested expression contains aggregate nodes:

query {
  products(where: { id: { lteq: 100 } }) {
    ratio: ratio(expr: {
      div: [
        { sum: { mul: [id, 2] } }
        { sum: id }
      ]
    })
  }
}

Expression arguments go through role allow-list checks. A role that cannot read price cannot leak it through sum(expr: { mul: [price, 2] }).

Analytics

Analytics directives keep rows visible while adding report metrics such as running totals, moving averages, previous/next values, first/last values, and rank within a group.

Use them when you need report-style columns but not a one-row-per-group aggregate result.

query {
  products {
    id
    price
    running_total: price @running(
      aggregate: sum
      by: "user_id"
      orderBy: { created_at: asc }
    )
    moving_avg: price @moving(
      aggregate: avg
      rows: 6
      by: "user_id"
      orderBy: { created_at: asc }
    )
    previous_price: price @previous(by: "user_id", orderBy: { created_at: asc })
    rank_by_price: price @rank(by: "user_id", order: desc)
  }
}

by accepts a column name or list of column names. orderBy uses the same object ordering shape as normal queries. order is shorthand for ordering by the annotated field. Analytics require a deterministic order.

Search

Full-text search is available through configured full-text columns and supported dialects.

query SearchProducts($query: String!) {
  products(search: $query, limit: 5) {
    id
    name
    search_rank
  }
}

SQL functions

PostgreSQL function fields can expose scalar values, table-returning functions, named args, user-defined return types, and directive behavior.

query {
  hotProducts(where: { productID: { eq: 55 } }, order_by: { productID: desc }) {
    productID
    countryCode
    countProductID
  }
}

Dialect boundaries