helixml / dagger

Query Building

This section outlines the querybuilder package, which handles constructing queries for the Helix platform.

Overview

The querybuilder package is designed to facilitate the building of structured queries for data retrieval from the Helix platform. It provides a flexible and expressive interface for crafting complex queries that can be customized to meet various data extraction needs.

Query Syntax

The querybuilder package utilizes a query syntax that closely mirrors the underlying structure of the Helix platform. Here’s a breakdown of the core components:

1. Entity Selection:

  • The core of the query is defined by specifying the entity (data type) you wish to retrieve. This is achieved through the select function.
query := querybuilder.Select("user")
  • The select function returns a QueryBuilder object that can be further customized.

2. Filtering (Where Clause):

  • Filtering conditions, known as the WHERE clause in SQL, are applied using the Where function.
query := querybuilder.Select("user").Where("name", "=", "Alice")
  • The Where function takes three arguments:
    • Field: The name of the field to filter on.
    • Operator: The comparison operator to use (e.g., =, >, <, !=, etc.).
    • Value: The value to compare against.

3. Ordering (OrderBy Clause):

  • The OrderBy function allows you to sort the retrieved data.
query := querybuilder.Select("user").OrderBy("name", "asc")
  • The OrderBy function takes two arguments:
    • Field: The name of the field to sort by.
    • Order: The sorting order (asc for ascending, desc for descending).

4. Pagination (Limit & Offset):

  • Pagination limits the number of results retrieved and sets an offset to skip a specific number of results.
query := querybuilder.Select("user").Limit(10).Offset(20)
  • The Limit function specifies the maximum number of results to return.
  • The Offset function skips a specified number of results.

5. Projection (Select Clause):

  • The SelectFields function defines the specific fields to retrieve.
query := querybuilder.Select("user").SelectFields("name", "email")
  • The SelectFields function takes a variable number of field names.

Example:

query := querybuilder.Select("user")
          query.Where("name", "=", "Bob")
          query.OrderBy("created_at", "desc")
          query.Limit(20)

Parameter Handling

The querybuilder package handles parameter substitution for safe and efficient query execution.

  • The WithArgs function is used to provide values for parameters.
query := querybuilder.Select("user")
          query.Where("name", "=", querybuilder.Param("name"))
          query.WithArgs(map[string]interface{}{"name": "Alice"})
  • The WithArgs function takes a map where the keys are the parameter names (as used in the query) and the values are the corresponding values.
  • Placeholders like :name or ? are used to represent parameters in the query.

Generating Queries

The querybuilder package provides the Build function to generate the final query string ready for execution.

query := querybuilder.Select("user")
          query.Where("name", "=", querybuilder.Param("name"))
          query.WithArgs(map[string]interface{}{"name": "Alice"})
          queryString := query.Build()
  • The Build function returns the complete query string with the parameters substituted.

Conclusion

The querybuilder package provides a powerful and flexible mechanism for constructing queries for the Helix platform. Its emphasis on parameterization ensures safe and efficient query execution, making it a valuable tool for data retrieval and manipulation within the context of the Helix platform.