Dimensions

Dimensions #

Dimension nodes are critical for defining the cross edges of the DJ DAG and are instrumental in many of DJ’s core features. They include a query that can select from any other node to create a representation of a dimension. Any column in any DJ node can then be tagged as a join key to any column on the dimension node. These join paths are used by DJ to discover all dimensions that are accessible for each metric. Some dimensions themselves may include join keys to other dimensions, further extending the join path and allowing DJ to discover more dimensions that can be used to group metrics.

Attribute Description Type
name Unique name used by other nodes to select from this node string
description A human readable description of the node string
mode published or draft (see Node Mode) string
query A SQL query that selects from other nodes string

Creating Dimension Nodes #

Dimension nodes can be created by making a POST request to /nodes/dimension/.

curl -X POST http://localhost:8000/nodes/dimension/ \
-H 'Content-Type: application/json' \
-d '{
    "name": "us_state",
    "description": "US state dimension",
    "mode": "published",
    "query": """
        SELECT
        state_id,
        state_name,
        state_abbr,
        state_region,
        r.us_region_description AS state_region_description
        FROM us_states s
        LEFT JOIN us_region r
        ON s.state_region = r.us_region_id
    """
}'
from djclient import DJ, Dimension

client = DJ("http://localhost:8000/")
client.push(
    Dimension(
        name="us_state",
        description="US state dimension",
        mode="published",
        query="""
            SELECT
            state_id,
            state_name,
            state_abbr,
            state_region,
            r.us_region_description AS state_region_description
            FROM us_states s
            LEFT JOIN us_region r
            ON s.state_region = r.us_region_id
        """,
    )
)

Connecting Node Columns to Dimensions #

Any column on any node can be identified as a join key to a dimension node column by making a POST request to the columns. For example, let’s assume you have a hard_hats node that contains employee information. The state in which the employee works is stored in a separate lookup table that includes a mapping of hard_hat_id to state_id.

This connection in DJ can be added using the following request.

curl -X POST \
http://localhost:8000/nodes/hard_hats/columns/hard_hat_id/?dimension=hard_hat_state&dimension_column=hard_hat_id \
-H 'Content-Type: application/json'
from djclient import DJ, Dimension

client = DJ("http://localhost:8000/")
client.set_dimension(
    node="hard_hats",
    column="hard_hat_id",
    dimension="hard_hat_state",
    dimension_column="hard_hat_id",
)