Hugr Lab

https://hugr-lab.github.io/docs
Admin
Hugr Lab is a project that provides a query engine with configurable settings and documentation for...
Tokens:594,870
Snippets:2,650
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Start Hugr Server and Example Infrastructure

Source: https://hugr-lab.github.io/docs/examples/duckdb-spatial

This command initiates the necessary services for the example, including the Hugr server and the DuckDB database. It's the first step to get the example environment running.

```bash
# Start the examples infrastructure  
scripts/start.sh  

```

--------------------------------

### Setup PostgreSQL Database with Northwind Schema

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This command navigates to the 'get-started' directory and executes a shell script to set up the PostgreSQL database with the Northwind schema. This is a prerequisite for the subsequent hugr configuration.

```shell
cd get-started
sh setup.sh
```

--------------------------------

### GraphQL Queries for Northwind Database

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

Examples of GraphQL queries that can be executed against the Northwind data source to retrieve specific information.

```APIDOC
## QUERY GetCustomersWithOrderSum

### Description
Retrieves a list of customers along with the sum of their orders from the Northwind database.

### Method
QUERY

### Endpoint
N/A (This is a GraphQL query executed against the hugr GraphQL endpoint)

### Parameters
None for this specific query structure.

### Request Example
```graphql
{
  northwind {
    customers {
      id
      company_name
      orders_aggregation{
        details{
          total{
            sum
          }
        }
      }
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **northwind.customers** (array) - An array of customer objects.
  - **id** (string) - The customer ID.
  - **company_name** (string) - The name of the customer's company.
  - **orders_aggregation** (object) - Aggregated order information for the customer.
    - **details** (object) - Details about the order aggregation.
      - **total** (object) - Total amount of orders.
        - **sum** (float) - The sum of order totals for the customer.

#### Response Example
```json
{
  "data": {
    "northwind": {
      "customers": [
        {
          "id": "ALFKI",
          "company_name": "Alfreds Futterkiste",
          "orders_aggregation": {
            "details": {
              "total": {
                "sum": 15000.50
              }
            }
          }
        }
        // ... more customers
      ]
    }
  }
}
```

## QUERY GetTotalAmountAndProductsByCategoryAndShipper

### Description
Aggregates the total amount and product count by category and shipper from the order details in the Northwind database.

### Method
QUERY

### Endpoint
N/A (This is a GraphQL query executed against the hugr GraphQL endpoint)

### Parameters
None for this specific query structure.

### Request Example
```graphql
{
  northwind {
    order_details_bucket_aggregation(
      order_by:[  
        {field: "aggregations.total.sum", direction: DESC}
      ]
    ){
      key{
        product{
          category{
            name
          }
        }
        order{
          shipper{
            company_name
          }
        }
      }
      aggregations{
        total{
          sum
        }
        quantity{
          sum
        }
      }
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **northwind.order_details_bucket_aggregation** (array) - Aggregated results.
  - **key** (object) - The grouping key.
    - **product** (object) - Product details.
      - **category** (object) - Category details.
        - **name** (string) - The name of the product category.
    - **order** (object) - Order details.
      - **shipper** (object) - Shipper details.
        - **company_name** (string) - The name of the shipping company.
  - **aggregations** (object) - Aggregated values.
    - **total** (object) - Total amount.
      - **sum** (float) - The sum of total amounts.
    - **quantity** (object) - Total quantity.
      - **sum** (integer) - The sum of quantities.

#### Response Example
```json
{
  "data": {
    "northwind": {
      "order_details_bucket_aggregation": [
        {
          "key": {
            "product": {
              "category": {
                "name": "Beverages"
              }
            },
            "order": {
              "shipper": {
                "company_name": "United Package"
              }
            }
          },
          "aggregations": {
            "total": {
              "sum": 5000.75
            },
            "quantity": {
              "sum": 120
            }
          }
        }
        // ... more aggregations
      ]
    }
  }
}
```

## QUERY GetShippedProductsByYearAndMonth

### Description
Retrieves the total number of shipped products and their amounts, bucketed by year and month from the Northwind database.

### Method
QUERY

### Endpoint
N/A (This is a GraphQL query executed against the hugr GraphQL endpoint)

### Parameters
None for this specific query structure.

### Request Example
```graphql
{
  northwind {
    orders_bucket_aggregation(
      filter: {
        shipped_date: {  
          is_null: false
        }
      }
      order_by: [
        {field: "key.year", direction: DESC}
        {field: "key.month", direction: DESC}
      ]
    ){
      key{
        year: _shipped_date_part(extract: year)
        month:_shipped_date_part(extract: month)
      }
      aggregations{
        _rows_count
        details{
          total{
            sum
          }
        }
      }
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **northwind.orders_bucket_aggregation** (array) - Aggregated order data.
  - **key** (object) - The grouping key.
    - **year** (integer) - The year of the shipped date.
    - **month** (integer) - The month of the shipped date.
  - **aggregations** (object) - Aggregated values.
    - **_rows_count** (integer) - The count of orders in the bucket.
    - **details** (object) - Details about the order aggregation.
      - **total** (object) - Total amount of orders.
        - **sum** (float) - The sum of order totals.

#### Response Example
```json
{
  "data": {
    "northwind": {
      "orders_bucket_aggregation": [
        {
          "key": {
            "year": 1998,
            "month": 12
          },
          "aggregations": {
            "_rows_count": 15,
            "details": {
              "total": {
                "sum": 12500.25
              }
            }
          }
        }
        // ... more year/month buckets
      ]
    }
  }
}
```
```

--------------------------------

### PostgreSQL: Setup Northwind Database Example

Source: https://hugr-lab.github.io/docs/category/examples

Guide to setting up a PostgreSQL database with the Northwind schema, including tables, functions, and relations. This provides step-by-step instructions for creating a sample database for GraphQL integration.

--------------------------------

### Documenting Hugr Notebook Environment Setup

Source: https://hugr-lab.github.io/docs/querying/python-client

Provides a template for documenting the necessary setup instructions at the beginning of a JupyterLab notebook that uses the Hugr client. This includes installing dependencies, configuring environment variables, and running the notebook.

```markdown
"""
# Setup Instructions

1. Install dependencies:
   pip install hugr-client pandas geopandas matplotlib keplergl

2. Configure environment:
   export HUGR_URL="http://your-hugr-server:15001/ipc"
   export HUGR_API_KEY="your-api-key"

3. Run notebook:
   jupyter notebook analysis.ipynb
"""
```

--------------------------------

### Manual Setup for OpenStreetMap Data with osm_dbt

Source: https://hugr-lab.github.io/docs/examples/duckdb-spatial

Details the manual steps for preparing OpenStreetMap data using the osm_dbt project. This includes cloning the project, installing dependencies, processing data for a specified region, and verifying the database statistics.

```bash
# 1. Navigate to data directory  
mkdir -p ../../data && cd ../../data  

# 2. Clone osm_dbt project  
git clone https://github.com/hugr-lab/osm_dbt.git osm  
cd osm  

# 3. Install dependencies  
pip install -r requirements.txt  
make install  

# 4. Process data (10-30 minutes)  
make quick-region REGION=bw TARGET=dev  

# 5. Verify database  
make stats REGION=bw TARGET=dev  

```

--------------------------------

### Setup MySQL HR CRM Database

Source: https://hugr-lab.github.io/docs/examples/mysql

This shell script sets up the MySQL database for the HR CRM example. It creates the 'hr_crm' database, defines tables, inserts sample data, and grants permissions to the 'hugr' user. It requires navigating to the example directory first.

```shell
cd examples/hr-crm
sh setup.sh
```

--------------------------------

### Add Northwind Data Source

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

Mutation to add the Northwind PostgreSQL database as a data source in hugr. This configures the connection and schema path.

```APIDOC
## MUTATE addNorthwindDataSet

### Description
Adds the Northwind PostgreSQL database as a data source within the hugr application. This involves specifying connection details, type, and schema location.

### Method
MUTATE

### Endpoint
N/A (This is a GraphQL mutation executed against the hugr admin UI)

### Parameters
#### Request Body
- **data** (object) - Required - The data source configuration object.
  - **name** (string) - Required - The name for the data source (e.g., "northwind").
  - **type** (string) - Required - The type of the data source (e.g., "postgres").
  - **prefix** (string) - Optional - A prefix for the data source (e.g., "nw").
  - **description** (string) - Optional - A description for the data source.
  - **read_only** (boolean) - Optional - Whether the data source is read-only.
  - **as_module** (boolean) - Optional - Whether to expose the data source as a module.
  - **path** (string) - Required - The connection string for the database (e.g., "postgres://hugr:hugr_password@postgres:5432/northwind").
  - **catalogs** (array) - Optional - An array of catalog configurations.
    - **name** (string) - Required - The name of the catalog.
    - **type** (string) - Required - The type of the catalog (e.g., "uri").
    - **description** (string) - Optional - A description for the catalog.
    - **path** (string) - Required - The path to the schema definition file.

### Request Example
```json
{
  "data": {
    "name": "northwind",
    "type": "postgres",
    "prefix": "nw",
    "description": "The Northwind database example",
    "read_only": false,
    "as_module": true,
    "path": "postgres://hugr:hugr_password@postgres:5432/northwind",
    "catalogs": [
      {
        "name": "northwind",
        "type": "uri",
        "description": "Northwind database schema",
        "path": "/workspace/examples/get-started/schema"
      }
    ]
  }
}
```

### Response
#### Success Response (200 OK)
- **core.insert_data_sources** (object) - Contains details of the newly inserted data source.
  - **name** (string) - The name of the data source.
  - **description** (string) - The description of the data source.
  - **as_module** (boolean) - Indicates if exposed as a module.
  - **disabled** (boolean) - Indicates if disabled.
  - **path** (string) - The path to the data source.
  - **prefix** (string) - The prefix of the data source.
  - **read_only** (boolean) - Indicates if read-only.
  - **self_defined** (boolean) - Indicates if self-defined.
  - **type** (string) - The type of the data source.
  - **catalogs** (array) - Array of catalog configurations.
    - **name** (string) - The name of the catalog.
    - **description** (string) - The description of the catalog.
    - **path** (string) - The path of the catalog.
    - **type** (string) - The type of the catalog.

#### Response Example
```json
{
  "data": {
    "core": {
      "insert_data_sources": {
        "name": "northwind",
        "description": "The Northwind database example",
        "as_module": true,
        "disabled": false,
        "path": "postgres://hugr:hugr_password@postgres:5432/northwind",
        "prefix": "nw",
        "read_only": false,
        "self_defined": false,
        "type": "postgres",
        "catalogs": [
          {
            "name": "northwind",
            "description": "Northwind database schema",
            "path": "/workspace/examples/get-started/schema",
            "type": "uri"
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Load Northwind Data Source

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

Mutation to manually load the 'northwind' data source after it has been created. This ensures the data source is ready for querying.

```APIDOC
## MUTATE loadNorthwindDataSource

### Description
Manually loads the specified data source, ensuring it is available for querying. This is typically done after initial setup or configuration changes.

### Method
MUTATE

### Endpoint
N/A (This is a GraphQL mutation executed against the hugr admin UI)

### Parameters
#### Request Body
- **name** (string) - Required - The name of the data source to load (e.g., "northwind").

### Request Example
```graphql
mutation {
  function {
    core {
      load_data_source(name: "northwind") {
        success
        message
      }
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **function.core.load_data_source.success** (boolean) - Indicates if the data source was loaded successfully.
- **function.core.load_data_source.message** (string) - A message providing details about the load operation.

#### Response Example
```json
{
  "data": {
    "function": {
      "core": {
        "load_data_source": {
          "success": true,
          "message": "Data source northwind loaded successfully"
        }
      }
    }
  }
}
```
```

--------------------------------

### Minikube: Basic Development Setup

Source: https://hugr-lab.github.io/docs/deployment/cluster

Provides essential commands for setting up a local Kubernetes development environment using Minikube. Includes starting Minikube, enabling ingress, applying configurations, and accessing services.

```bash
# Start Minikube with specified resources
minikube start --cpus=4 --memory=8192

# Enable the ingress controller addon
minikube addons enable ingress

# Apply Kubernetes configurations from a local directory
kubectl apply -f k8s/cluster/

# Get the URL for accessing the hugr-worker service
minikube service hugr-worker --url
```

--------------------------------

### Example: Many-to-Many Relationship Setup

Source: https://hugr-lab.github.io/docs/references/directives

This example outlines the setup for a many-to-many relationship between 'products' and 'categories' by defining a join table that references both. While the join table itself isn't shown here, the definitions for 'categories' and 'products' are provided, implying a third table would link them.

```graphql
type categories @table(name: "categories") {
  id: BigInt! @pk
  name: String!
  description: String
}

type products @table(name: "products") {
  id: BigInt! @pk
  name: String!
  description: String
  price: Float!
}
```

--------------------------------

### JWT Token Example

Source: https://hugr-lab.github.io/docs/deployment/auth

An example JSON payload for a JWT token, demonstrating standard claims like 'sub', 'name', 'email', 'role', and custom claims like 'scope'.

```json
{
  "sub": "user123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "editor",
  "scope": "read write",
  "iss": "https://your-auth-provider.com",
  "aud": "your-api-audience",
  "exp": 1735689600
}

```

--------------------------------

### Load hugr Data Source Manually

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL mutation manually loads the 'northwind' data source after it has been configured in `hugr`. This action is necessary to make the data source available for querying. It returns a success status and a message.

```graphql
mutation {
  function {
    core {
      load_data_source(name: "northwind") {
        success
        message
      }
    }
  }
}
```

--------------------------------

### Add Northwind PostgreSQL Data Source to hugr

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL mutation adds the Northwind PostgreSQL database as a data source within the `hugr` administration UI. It specifies connection details, schema path, and other configurations necessary for `hugr` to interact with the database.

```graphql
mutation addNorthwindDataSet($data: data_sources_mut_input_data! = {}) {
  core {
    insert_data_sources(data: $data) {
      name
      description
      as_module
      disabled
      path
      prefix
      read_only
      self_defined
      type
      catalogs {
        name
        description
        path
        type
      }
    }
  }
}

```

```json
{
  "data": {
    "name": "northwind",
    "type": "postgres",
    "prefix": "nw",
    "description": "The Northwind database example",
    "read_only": false,
    "as_module": true,
    "path": "postgres://hugr:hugr_password@postgres:5432/northwind",
    "catalogs": [
      {
        "name": "northwind",
        "type": "uri",
        "description": "Northwind database schema",
        "path": "/workspace/examples/get-started/schema"
      }
    ]
  }
}
```

--------------------------------

### Example GET Request with Variables

Source: https://hugr-lab.github.io/docs/querying/graphql

Illustrates a GET request to the /query endpoint including URL-encoded variables and an operation name.

```bash
curl -X GET "http://localhost:8080/query?query=query%20GetUser(%24id%3A%20Int!)%20%7B%20users(filter%3A%20%7Bid%3A%20%7Beq%3A%20%24id%7D%7D)%20%7B%20id%20name%20%7D%20%7D&variables=%7B%22id%22%3A%201%7D"
```

--------------------------------

### Get Total Shipped Products by Month (Filtered by Supplier Country in Details)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

Retrieves the total count and sum of shipped product amounts per month. It filters the details of the aggregated orders to include only products supplied by companies in Finland or France.

```APIDOC
## Get Total Shipped Products by Month (Filtered by Supplier Country in Details)

### Description
This endpoint aggregates orders by month based on their shipped date. It then filters the order details to include only products supplied by companies in Finland or France, and calculates the total amount for these filtered products. The aggregation returns the total number of orders and the sum of the product amounts for each month.

### Method
POST

### Endpoint
/graphql

### Request Body
```json
{
  "query": "\n  northwind {\n    orders_bucket_aggregation(\n      filter: {\n        shipped_date: {\n          is_null: false\n        }\n      }\n      order_by: [\n        {field: \"key.bucket\", direction: DESC}\n      ]\n    ){\n      key{\n        bucket: shipped_date(bucket: month)\n      }\n      aggregations{\n        _rows_count\n        details(\n          filter:{\n            product:{\n              supplier:{\n                country: {in: [\"Finland\", \"France\"]}\n              }\n            }\n          }\n        ){\n          total{\n            sum\n          }\n        }\n      }\n    }\n  }\n}
  "
}
```

### Response
#### Success Response (200)
- **key.bucket** (String) - The month of the shipped orders.
- **aggregations._rows_count** (Int) - The total number of orders in that month.
- **aggregations.details.total.sum** (Float) - The total amount of shipped products (filtered by supplier country) in that month.

#### Response Example
```json
{
  "data": {
    "northwind": {
      "orders_bucket_aggregation": [
        {
          "key": {
            "bucket": "2023-10"
          },
          "aggregations": {
            "_rows_count": 50,
            "details": {
              "total": {
                "sum": 1150.20
              }
            }
          }
        },
        {
          "key": {
            "bucket": "2023-09"
          },
          "aggregations": {
            "_rows_count": 45,
            "details": {
              "total": {
                "sum": 1050.00
              }
            }
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Get Total Shipped Products by Month (Filtered by Supplier Origin)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

Retrieves the total count and sum of shipped product amounts per month, specifically for orders where products were supplied by companies in Finland or France.

```APIDOC
## Get Total Shipped Products by Month (Filtered by Supplier Origin)

### Description
This endpoint aggregates orders by month based on their shipped date. It filters these orders to include only those where the products were supplied by companies located in Finland or France. The aggregation returns the total number of orders and the sum of the product amounts within these orders for each month.

### Method
POST

### Endpoint
/graphql

### Request Body
```json
{
  "query": "\n  northwind {\n    orders_bucket_aggregation(
      filter: {\n        shipped_date: {\n          is_null: false\n        }\n        details: {\n          any_of: {\n            product:{\n              supplier:{\n                country: {in: [\"Finland\", \"France\"]}\n              }\n            }\n          }\n        }\n      }\n      order_by: [\n        {field: \"key.bucket\", direction: DESC}\n      ]\n    ){\n      key{\n        bucket: shipped_date(bucket: month)\n      }\n      aggregations{\n        _rows_count\n        details{\n          total{\n            sum\n          }\n        }\n      }\n    }\n  }\n}
  "
}
```

### Response
#### Success Response (200)
- **key.bucket** (String) - The month of the shipped orders.
- **aggregations._rows_count** (Int) - The total number of orders in that month.
- **aggregations.details.total.sum** (Float) - The total amount of shipped products in that month.

#### Response Example
```json
{
  "data": {
    "northwind": {
      "orders_bucket_aggregation": [
        {
          "key": {
            "bucket": "2023-10"
          },
          "aggregations": {
            "_rows_count": 50,
            "details": {
              "total": {
                "sum": 1250.75
              }
            }
          }
        },
        {
          "key": {
            "bucket": "2023-09"
          },
          "aggregations": {
            "_rows_count": 45,
            "details": {
              "total": {
                "sum": 1100.50
              }
            }
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Example GET Request for Simple GraphQL Query

Source: https://hugr-lab.github.io/docs/querying/graphql

Shows a basic GET request to the /query endpoint for a simple GraphQL query without variables.

```bash
curl -X GET "http://localhost:8080/query?query=%7B%20users%20%7B%20id%20name%20email%20%7D%20%7D"
```

--------------------------------

### Query: Customers and Order Sums (Northwind GraphQL)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL query retrieves a list of customers from the 'northwind' data source, including their company name and the sum of their orders. It demonstrates basic data retrieval and aggregation capabilities of the generated schema.

```graphql
{
  northwind {
    customers {
      id
      company_name
      orders_aggregation{
        details{
          total{
            sum
          }
        }
      }
    }
  }
}
```

--------------------------------

### Query: Shipped Products by Year and Month (Northwind GraphQL)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL query calculates the total shipped products (amount) aggregated by year and month. It filters orders to include only those that have been shipped and orders the results by year and month in descending order.

```graphql
{
  northwind {
    orders_bucket_aggregation(
      filter: {
        shipped_date: {
          is_null: false
        }
      }
      order_by: [
        {field: "key.year", direction: DESC}
        {field: "key.month", direction: DESC}
      ]
    ){
      key{
        year: _shipped_date_part(extract: year)
        month:_shipped_date_part(extract: month)
      }
      aggregations{
        _rows_count
        details{
          total{
            sum
          }
        }
      }
    }
  }
}
```

--------------------------------

### Quick Setup for OpenStreetMap Data

Source: https://hugr-lab.github.io/docs/examples/duckdb-spatial

Provides one-line commands to quickly set up the OpenStreetMap dataset for DuckDB. It supports default regions, custom regions like 'berlin', and options to force a fresh clone of the data.

```bash
# Default Baden-Württemberg region  
cd examples/osm && bash setup.sh  

# Custom region  
cd examples/osm && bash setup.sh --region berlin  

# Force fresh setup  
cd examples/osm && bash setup.sh --force-clone  

```

--------------------------------

### Define Shipped Products View with SQL

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This code defines a database view named 'shipped_products_view' using SQL. It joins the 'orders', 'order_details', and 'products' tables to retrieve comprehensive information about products that have been shipped. The view filters for orders where 'shipped_date' is not null.

```sql
CREATE VIEW shipped_products_view AS
SELECT
  orders.customer_id,
  orders.employee_id,
  orders.order_date,
  orders.shipped_date,
  orders.ship_via,
  order_details.product_id,
  order_details.unit_price,
  order_details.quantity,
  order_details.discount,
  products.supplier_id,
  products.category_id
FROM orders
    INNER JOIN order_details ON orders.order_id = order_details.order_id
    INNER JOIN products ON order_details.product_id = products.product_id
WHERE orders.shipped_date IS NOT NULL;
```

--------------------------------

### Shipped Products View Schema Definition

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This code defines the schema for the 'shipped_products_view', specifying the data types for each field and establishing field references to related entities. It also includes a computed 'total' field for the order item price.

```graphql
type shipped_products_view
  @view(
    name: "shipped_products"
    sql: ""
    )
{
  customer_id: String! @field_references(
    name: "shipped_products_view_customer_id"
    references_name: "customers"
    field: "id"
    query: "customer"
    description: "Customer"
    references_query: "shippedProducts"
    references_description: "Shipped products for this customer"
  )
  employee_id: Int! @field_references(
    name: "shipped_products_view_employee_id"
    references_name: "employees"
    field: "id"
    query: "employee"
    description: "Employee"
    references_query: "shippedProducts"
    references_description: "Shipped products handled by this employee"
  )
  order_date: Timestamp
  shipped_date: Timestamp
  ship_via: Int @field_references(
    name: "shipped_products_view_ship_via"
    references_name: "shippers"
    field: "id"
    query: "shipper"
    description: "Shipper"
    references_query: "shippedProducts"
    references_description: "Shipped products by this shipper"
  )
  product_id: Int! @field_references(
    name: "shipped_products_view_product_id"
    references_name: "products"
    field: "id"
    query: "product"
    description: "Product"
    references_query: "shippedProducts"
    references_description: "Shipped product details in this order"
  )
  unit_price: Float!
  quantity: Int!
  discount: Float!
  supplier_id: Int! @field_references(
    name: "shipped_products_view_supplier_id"
    references_name: "suppliers"
    field: "id"
    query: "supplier"
    description: "Supplier of the product in the order details view."
  )
  category_id: Int! @field_references(
    name: "shipped_products_view_category_id"
    references_name: "categories"
    field: "id"
    query: "category"
    description:
      "Category of the product in the order details view."
  )
  total: Float! @sql(exp: "round(([unit_price] * [quantity] * (1 - [discount]))*100)/100")
}
```

--------------------------------

### Aggregate Shipped Products by Month and Supplier Country (GraphQL)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL query retrieves the total amount of shipped products aggregated by month. It filters orders to include only those shipped by suppliers from Finland and France, and applies the filter within the 'details' aggregation.

```graphql
{
  northwind {
    orders_bucket_aggregation(
      filter: {
        shipped_date: {
          is_null: false
        }
        details: {
          any_of: {
            product:{
              supplier:{
                country: {in: ["Finland", "France"]}
              }
            }
          }
        }
      }
      order_by: [
        {field: "key.bucket", direction: DESC}
      ]
    ){
      key{
        bucket: shipped_date(bucket: month)
      }
      aggregations{
        _rows_count
        details{
          total{
            sum
          }
        }
      }
    }
  }
}
```

--------------------------------

### Query: Aggregated Order Details by Category and Shipper (Northwind GraphQL)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL query performs a complex aggregation on order details, grouping by product category and shipper. It calculates the total sum and quantity for each group and orders the results by the total sum in descending order.

```graphql
{
  northwind {
    order_details_bucket_aggregation(
      order_by:[
        {field: "aggregations.total.sum", direction: DESC}
      ]
    ){
      key{
        product{
          category{
            name
          }
        }
        order{
          shipper{
            company_name
          }
        }
      }
      aggregations{
        total{
          sum
        }
        quantity{
          sum
        }
      }
    }
  }
}
```

--------------------------------

### Aggregate Shipped Products by Month (GraphQL)

Source: https://hugr-lab.github.io/docs/examples/postgres-get-started

This GraphQL query calculates the total amount of shipped products aggregated by month. It filters out orders that have not been shipped. The supplier country filtering is applied within the 'details' aggregation, targeting products supplied by Finland and France.

```graphql
{
  northwind {
    orders_bucket_aggregation(
      filter: {
        shipped_date: {
          is_null: false
        }
      }
      order_by: [
        {field: "key.bucket", direction: DESC}
      ]
    ){
      key{
        bucket: shipped_date(bucket: month)
      }
      aggregations{
        _rows_count
        details(
          filter:{
            product:{
              supplier:{
                country: {in: ["Finland", "France"]}
              }
            }
          }
        ){
          total{
            sum
          }
        }
      }
    }
  }
}
```

--------------------------------

### JWT Token with Scopes Example

Source: https://hugr-lab.github.io/docs/deployment/auth

An example JSON payload for a JWT token that includes 'scopes', demonstrating how a role can be embedded within a scope string.

```json
{
  "scope": "read write role:editor"
}

```

--------------------------------

### Prepare DuckDB OSM Data (Shell Script)

Source: https://hugr-lab.github.io/docs/examples/duckdb-spatial

This shell command navigates to the 'examples/osm' directory and executes the 'setup.sh' script with the '--region bayern' argument. This prepares the DuckDB database with OpenStreetMap data for the Bayern region.

```bash
cd examples/osm && bash setup.sh --region bayern
```

--------------------------------

### Configure hugr-client Startup in JupyterHub

Source: https://hugr-lab.github.io/docs/querying/python-client

Sets up environment variables for hugr-client configuration within the JupyterHub user environment by creating a startup script. This script defines connection details, API key headers, and role headers, enabling users to connect to the hugr server automatically.

```python
import os  

# Configure default hugr connection  
os.environ['HUGR_URL'] = 'http://hugr-server.internal:15001/ipc'
os.environ['HUGR_API_KEY_HEADER'] = 'X-API-Key'
os.environ['HUGR_ROLE_HEADER'] = 'X-User-Role'  

# Per-user authentication can be set in notebook cells  
```

--------------------------------

### OIDC Token Example

Source: https://hugr-lab.github.io/docs/deployment/auth

An example JSON payload for an OpenID Connect (OIDC) ID token, showing standard claims like 'iss', 'sub', 'aud', 'iat', 'exp', and identity-related claims like 'email', 'name', and 'role'.

```json
{
  "iss": "https://accounts.google.com",
  "sub": "110169484474386276334",
  "azp": "your-client-id",
  "aud": "your-client-id",
  "iat": 1735689000,
  "exp": 1735692600,
  "email": "john@example.com",
  "email_verified": true,
  "name": "John Doe",
  "picture": "https://...",
  "role": "editor"
}

```

--------------------------------

### Keycloak OIDC Integration Configuration

Source: https://hugr-lab.github.io/docs/deployment/auth

Configuration example for integrating Hugr with Keycloak using OpenID Connect (OIDC). This setup specifies OIDC enablement, the issuer URL for the Keycloak realm, client credentials, and the role claim path within the token.

```yaml
auth:
  oidc:
    enabled: true
    issuer: "https://keycloak.example.com/realms/your-realm"
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    role_claim: "realm_access.roles"

```

--------------------------------

### Querying Data - Get Districts

Source: https://hugr-lab.github.io/docs/examples/duckdb-spatial

Query for all districts in Baden-Württemberg, including their centroids and road lengths by class.

```APIDOC
## Querying Data - Get Districts

### Description
Retrieves all districts in Baden-Württemberg, their centroids, and aggregated road lengths by class.

### Method
`query`

### Endpoint
N/A (GraphQL Query)

### Parameters
None

### Request Example
```graphql
query getDistricts {
  osm {
    bw {
      osm_administrative_boundaries(filter: {admin_level: {eq: 6}}) {
        osm_id
        name
        name_de
        region_code
        area_sqm
        centroid: geom(transforms: Centroid)
        _spatial(field: "geom", type: INTERSECTS){
          osm_bw_osm_roads_bucket_aggregation(field: "geom"){
            key{
              road_class
            }
            aggregations{
              len: _geom_measurement(type: LengthSpheroid){
                sum
              }
            }
          }
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **osm_id** (String) - The unique identifier for the administrative boundary.
- **name** (String) - The name of the district.
- **name_de** (String) - The German name of the district.
- **region_code** (String) - The region code of the district.
- **area_sqm** (Float) - The area of the district in square meters.
- **centroid** (String) - The centroid of the district geometry (e.g., WKT format).
- **_spatial** (Object) - Spatial data including road aggregations.
  - **road_class** (String) - The class of the road.
  - **sum** (Float) - The total length of roads of a specific class within the district.

#### Response Example
```json
{
  "data": {
    "osm": {
      "bw": {
        "osm_administrative_boundaries": [
          {
            "osm_id": "12345",
            "name": "Stuttgart",
            "name_de": "Stuttgart",
            "region_code": "BW-S",
            "area_sqm": 207350000.0,
            "centroid": "POINT(9.1818 48.7758)",
            "_spatial": {
              "osm_bw_osm_roads_bucket_aggregation": [
                {
                  "key": {
                    "road_class": "motorway"
                  },
                  "aggregations": {
                    "len": {
                      "sum": 150.5
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### GraphQL Query Examples

Source: https://hugr-lab.github.io/docs/graphql/queries

Illustrative examples of GraphQL queries demonstrating basic queries, nested modules, and function calls.

```APIDOC
## GraphQL Query Examples

### Description
These examples showcase how to structure GraphQL queries to fetch data, including accessing nested modules and invoking functions.

### Method
POST

### Endpoint
/graphql

### Request Body
**query** (String) - The GraphQL query string.

### Request Example
```json
{
  "query": "query {\n  # Root level objects\n  customers { id name }\n  customers_aggregation { _rows_count }\n  customers_by_pk(id: 1) { id name }\n\n  # Nested modules - data objects inside modules\n  crm {\n    analytics {\n      # All query types available within modules\n      top_customers { id total_spent }\n      top_customers_aggregation { _rows_count }\n      top_customers_bucket_aggregation {\n        key { segment }\n        aggregations { _rows_count }\n      }\n    }\n  }\n\n  # Functions organized in modules\n  function {\n    services {\n      weather {\n        current_weather(lat: 40.7, lon: -74.0) {\n          temp\n        }\n      }\n    }\n  }\n}"
}
```

### Response
#### Success Response (200)
- **data** (Object) - The response data from the GraphQL query.

#### Response Example
```json
{
  "data": {
    "customers": [
      { "id": 1, "name": "Alice" },
      { "id": 2, "name": "Bob" }
    ],
    "customers_aggregation": {
      "_rows_count": 2
    },
    "customers_by_pk": {
      "id": 1,
      "name": "Alice"
    },
    "crm": {
      "analytics": {
        "top_customers": [
          { "id": 1, "total_spent": 150.75 },
          { "id": 2, "total_spent": 210.50 }
        ],
        "top_customers_aggregation": {
          "_rows_count": 2
        },
        "top_customers_bucket_aggregation": {
          "key": {"segment": "New"},
          "aggregations": {"_rows_count": 1}
        }
      }
    },
    "function": {
      "services": {
        "weather": {
          "current_weather": {
            "temp": 72.5
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### GET /data/2.5/weather

Source: https://hugr-lab.github.io/docs/examples/rest-owm

Retrieves current weather data for a specified geographical location using latitude and longitude.

```APIDOC
## GET /data/2.5/weather

### Description
Fetches current weather information from OpenWeatherMap based on provided latitude and longitude.

### Method
GET

### Endpoint
/data/2.5/weather

### Parameters
#### Query Parameters
- **lat** (number) - Required - Latitude of the location
- **lon** (number) - Required - Longitude of the location

### Request Example
```
GET /data/2.5/weather?lat=34.0522&lon=-118.2437
```

### Response
#### Success Response (200)
- **current_weather** (object) - Schema defining the current weather data structure.

#### Response Example
```json
{
  "coord": {
    "lon": -0.13,
    "lat": 51.51
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 282.55,
    "feels_like": 281.86,
    "temp_min": 280.37,
    "temp_max": 284.26,
    "pressure": 1023,
    "humidity": 81
  },
  "visibility": 10000,
  "wind": {
    "speed": 1.54,
    "deg": 0
  },
  "clouds": {
    "all": 1
  },
  "dt": 1560350645,
  "sys": {
    "type": 1,
    "id": 5091,
    "country": "GB",
    "sunrise": 1560343627,
    "sunset": 1560399877
  },
  "timezone": 3600,
  "id": 2643743,
  "name": "London",
  "cod": 200
}
```
```

--------------------------------

### Start JupyterLab Server

Source: https://hugr-lab.github.io/docs/querying/python-client

A simple command to launch the JupyterLab application. This command initiates the JupyterLab server, making it accessible through a web browser for interactive computing and development.

```bash
jupyter lab  
```

--------------------------------

### GET /data/2.5/weather

Source: https://hugr-lab.github.io/docs/examples/rest-owm

Retrieves the current weather data for a specified geographical location using latitude and longitude.

```APIDOC
## GET /data/2.5/weather

### Description
Fetches the current weather conditions for a specific location based on its latitude and longitude coordinates.

### Method
GET

### Endpoint
/data/2.5/weather

### Parameters
#### Query Parameters
- **lat** (number) - Required - Latitude of the location.
- **lon** (number) - Required - Longitude of the location.

### Request Example
```
GET https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={apiKey}
```

### Response
#### Success Response (200)
- **current_weather** (object) - Contains detailed current weather information including temperature, weather conditions, wind, clouds, and system information.

#### Response Example
```json
{
  "id": 524901, 
  "name": "Moscow", 
  "base": "stations", 
  "coord": {
    "lat": 55.7522, 
    "lon": 37.6156 
  },
  "dt": 1661870592,
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "clouds": {
    "all": 0
  },
  "wind": {
    "speed": 2,
    "deg": 210,
    "gust": 4.5
  },
  "main": {
    "temp": 24.5,
    "feels_like": 23.8,
    "temp_min": 23.0,
    "temp_max": 25.5,
    "humidity": 50,
    "pressure": 1012,
    "sea_level": 1012,
    "grnd_level": 1005
  },
  "sys": {
    "country": "RU",
    "sunrise": 1661839000,
    "sunset": 1661891000
  }
}
```
```
Tokens:
Raw