Skip to main content

GraphQL Queries

Hugr automatically generates a comprehensive GraphQL API from your schema definitions, providing powerful query capabilities for data access and manipulation. This section covers all aspects of querying data through the generated GraphQL API.

What Gets Generated​

For each data object (table or view) defined in your schema, Hugr automatically creates:

  • Basic queries - Select multiple records with filtering, sorting, and pagination
  • Primary key queries - Retrieve single records by primary key (<object>_by_pk)
  • Unique constraint queries - Retrieve single records by unique fields (<object>_by_<field>)
  • Aggregation queries - Single-row aggregations (<object>_aggregation)
  • Bucket aggregations - Grouped aggregations (<object>_bucket_aggregation)
  • Relation fields - Access related data through foreign keys
  • Function fields - Execute functions with automatic argument mapping

Query Organization​

All queries are organized in a hierarchical module structure based on the @module directive. Data objects, aggregations, and functions can be nested within modules at any level.

query {
  # Root level objects
  customers { id name }
  customers_aggregation { _rows_count }
  customers_by_pk(id: 1) { id name }

  # Nested modules - data objects inside modules
  crm {
    analytics {
      # All query types available within modules
      top_customers { id total_spent }
      top_customers_aggregation { _rows_count }
      top_customers_bucket_aggregation {
        key { segment }
        aggregations { _rows_count }
      }
    }
  }

  # Functions organized in modules
  function {
    services {
      weather {
        current_weather(lat: 40.7, lon: -74.0) {
          temp
        }
      }
    }
  }
}

Module structure:

  • Defined using @module(name: "module.submodule") directive
  • Can nest data objects at any depth
  • All query types (<object>, <object>_by_pk, <object>_aggregation, <object>_bucket_aggregation) available within modules
  • Functions organized under function field can also be modularized

Core Query Capabilities​

1. Function Calls​

Execute database functions, HTTP API calls, and custom business logic directly in queries.

Learn about Function Calls →

2. Basic Queries​

Retrieve records by primary key or unique constraints with simple, direct queries.

Learn about Basic Queries →

3. Filtering​

Apply complex filters using boolean logic, relation filters, and nested conditions.

Learn about Filtering →

4. Sorting & Pagination​

Order results and implement pagination with limit/offset and distinct operations.

Learn about Sorting & Pagination →

5. Relations​

Query related data through foreign keys with nested queries and aggregations.

Learn about Relations →

6. Function Fields​

Embed function calls as fields in data objects with automatic argument mapping.

Learn about Function Fields →

7. Aggregations​

Perform single-row and grouped aggregations with support for nested aggregations.

Learn about Aggregations →

8. Dynamic Joins​

Create ad-hoc joins at query time using the _join field, including cross-source joins.

Learn about Dynamic Joins →

9. Spatial Queries​

Query geographically related data using spatial relationships and operations.

Learn about Spatial Queries →

10. H3 Hexagonal Clustering​

Aggregate and cluster spatial data using the H3 hexagonal grid system for advanced geospatial analysis.

Learn about H3 Clustering →

Perform semantic search using vector embeddings with support for multiple distance metrics and hybrid search.

Learn about Vector Search →

12. Generated Fields & Transformations​

Use automatically generated fields and transformation arguments for Timestamp, JSON, and Geometry data types.

Learn about Generated Fields →

13. Cube & Hypertable Queries​

Query OLAP cubes and time-series hypertables with measurement aggregation and time-based bucketing.

Learn about Cube & Hypertable Queries →

Query Arguments Reference​

Most query types support these standard arguments:

ArgumentTypeDescription
filter<object>_filterFilter conditions for records
order_by[OrderByField]Sort order (can reference nested fields)
limitIntMaximum number of records to return
offsetIntNumber of records to skip
distinct_on[String]Fields to use for DISTINCT
args<input_type>Arguments for parameterized views
innerBooleanUse INNER join (excludes parent records without matches, default: false)

Nested Query Arguments​

For relation fields (subqueries), additional arguments control post-join behavior:

ArgumentTypeDescription
nested_order_by[OrderByField]Sort order applied after join
nested_limitIntLimit applied after join
nested_offsetIntOffset applied after join

Common Patterns​

Basic Data Retrieval​

query {
  customers(
    filter: { country: { eq: "USA" } }
    order_by: [{ field: "name", direction: ASC }]
    limit: 10
  ) {
    id
    name
    email
  }
}

Data with Relations​

query {
  customers {
    id
    name
    orders(
      filter: { status: { eq: "pending" } }
      limit: 5
    ) {
      id
      total
    }
  }
}

Aggregations​

query {
  orders_bucket_aggregation {
    key {
      status
    }
    aggregations {
      _rows_count
      total {
        sum
        avg
      }
    }
  }
}

Function Calls​

query {
  function {
    weather {
      current_weather(lat: 40.7, lon: -74.0) {
        temp
        humidity
      }
    }
  }
}

Performance Best Practices​

  1. Use filters early - Apply filters at the highest level possible to reduce data volume
  2. Limit nested queries - Always use limit or nested_limit for one-to-many relations
  3. Leverage indexes - Ensure indexes exist on filtered and sorted fields
  4. Aggregate when possible - Use aggregation queries instead of fetching raw data
  5. Batch related data - Use subqueries instead of separate queries to avoid N+1 problems

Next Steps​

Start with Function Calls to learn how to execute functions, or jump to Basic Queries for fundamental data retrieval patterns.