> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Column expressions

> Reference for table column expressions in Junction Sense queries to select fields from activity, body, sleep, and timeseries resources.

## Table Column expression

Your Query Instruction can pull data from [Junction summary and timeseries resources](/wearables/providers/resources)
through Table Column expressions.

Each Table Column expression can select one column (a field) of the table (the Junction resource).
You can use multiple Table Column expressions to select multiple columns in the same query.

<Info>
  Cross-table query instructions are not supported — you cannot mix Table Column expressions from
  different tables in the same query instruction.
</Info>

<Note>
  Column expressions for Electrocardiogram, Sleep Cycle, and lab testing biomarkers are planned to be introduced in the future.
</Note>

### Summaries

| Table                                     | Python DSL                   | JSON DSL                        |
| ----------------------------------------- | ---------------------------- | ------------------------------- |
| Activity daily summary<br />`activity`    | `Activity.col("$1")`         | `{ "activity": "$1" }`          |
| Body summary<br />`body`                  | `Body.col("$1")`             | `{ "body": "$1" }`              |
| Sleep summary<br />`sleep`                | `Sleep.col("$1")`            | `{ "sleep": "$1" }`             |
| Readiness scores<br />`derived_readiness` | `DerivedReadiness.col("$1")` | `{ "derived_readiness": "$1" }` |
| Workout summary<br />`workout`            | `Workout.col("$1")`          | `{ "workout": "$1" }`           |
| Meal summary<br />`meal`                  | `Meal.col("$1")`             | `{ "meal": "$1" }`              |
| Menstrual cycle<br />`menstrual_cycle`    | `MenstrualCycle.col("$1")`   | `{ "menstrual_cycle": "$1" }`   |
| Profile<br />`profile`                    | `Profile.col("$1")`          | `{ "profile": "$1" }`           |

### Column Mappings

Map summary resource properties to their Continuous Query column equivalents.

#### Sleep

| Sleep field                | Query Column               |
| -------------------------- | -------------------------- |
| `calendar_date`            | `index`                    |
| `bedtime_start`            | `session_start`            |
| `bedtime_stop`             | `session_end`              |
| `type`                     | `type`                     |
| `timezone_offset`          | `time_zone`                |
| `duration`                 | `duration_second`          |
| `total`                    | `stage_asleep_second`      |
| `awake`                    | `stage_awake_second`       |
| `light`                    | `stage_light_second`       |
| `rem`                      | `stage_rem_second`         |
| `deep`                     | `stage_deep_second`        |
| -                          | `stage_unknown_second`     |
| `score`                    | `score`                    |
| `recovery_readiness_score` | `recovery_readiness_score` |
| `hr_lowest`                | `heart_rate_minimum`       |
| `hr_average`               | `heart_rate_mean`          |
| -                          | `heart_rate_maximum`       |
| `hr_resting`               | `heart_rate_resting`       |
| `efficiency`               | `efficiency`               |
| `latency`                  | `latency_second`           |
| `temperature_delta`        | `skin_temperature_delta`   |
| `skin_temperature`         | `skin_temperature`         |
| `hr_dip`                   | `heart_rate_dip`           |
| `average_hrv`              | `hrv_mean_rmssd`           |
| -                          | `hrv_mean_sdnn`            |
| `respiratory_rate`         | `respiratory_rate`         |
| `state`                    | `state`                    |
| `source.slug`              | `source_provider`          |
| `source.type`              | `source_type`              |
| `source.device_id`         | `source_device_id`         |
| `source.app_id`            | `source_app_id`            |

#### Activity

| Activity field               | Query Column                 |
| ---------------------------- | ---------------------------- |
| `calendar_date`              | `index`                      |
| `calories_total`             | `calories_total`             |
| `calories_active`            | `calories_active`            |
| `steps`                      | `steps`                      |
| `daily_movement`             | `duration_active_second`     |
| `distance`                   | `distance_meter`             |
| `floors_climbed`             | `floors_climbed`             |
| `time_zone`                  | `time_zone`                  |
| `timezone_offset`            | `time_zone_offset`           |
| `heart_rate.avg_bpm`         | `heart_rate_mean`            |
| `heart_rate.min_bpm`         | `heart_rate_minimum`         |
| `heart_rate.max_bpm`         | `heart_rate_maximum`         |
| `heart_rate.resting_bpm`     | `heart_rate_resting`         |
| `heart_rate.avg_walking_bpm` | `heart_rate_mean_walking`    |
| `wheelchair_use`             | `wheelchair_use`             |
| `wheelchair_push`            | `wheelchair_push`            |
| -                            | `intensity_sedentary_second` |
| `low`                        | `intensity_low_second`       |
| `medium`                     | `intensity_medium_second`    |
| `high`                       | `intensity_high_second`      |
| `source.slug`                | `source_provider`            |
| `source.type`                | `source_type`                |
| `source.device_id`           | `source_device_id`           |
| `source.app_id`              | `source_app_id`              |

#### Workout

| Workout field            | Query Column              |
| ------------------------ | ------------------------- |
| `title`                  | `title`                   |
| `timezone_offset`        | `time_zone`               |
| `average_hr`             | `heart_rate_mean`         |
| `max_hr`                 | `heart_rate_maximum`      |
| -                        | `heart_rate_minimum`      |
| `distance`               | `distance_meter`          |
| `calendar_date`          | -                         |
| `time_start`             | `session_start`           |
| `time_end`               | `session_end`             |
| `calories`               | `calories`                |
| `sport.name`             | `sport_name`              |
| `sport.slug`             | `sport_slug`              |
| `hr_zones`               | `heart_rate_zone_1..6`    |
| `moving_time`            | `duration_active_second`  |
| `total_elevation_gain`   | `elevation_gain_meter`    |
| `elev_high`              | `elevation_maximum_meter` |
| `elev_low`               | `elevation_minimum_meter` |
| `average_speed`          | `speed_mean`              |
| `max_speed`              | `speed_maximum`           |
| `average_watts`          | `power_mean`              |
| `device_watts`           | `power_source`            |
| `max_watts`              | `power_maximum`           |
| `weighted_average_watts` | `power_weighted_mean`     |
| `steps`                  | `steps`                   |
| `map.polyline`           | `map_polyline`            |
| `map.summary_polyline`   | `map_summary_polyline`    |
| `provider_id`            | `external_id`             |
| `source.slug`            | `source_provider`         |
| `source.type`            | `source_type`             |
| `source.device_id`       | `source_device_id`        |
| `source.app_id`          | `source_app_id`           |

#### Body

| Body field                       | Query Column                     |
| -------------------------------- | -------------------------------- |
| `calendar_date`                  | -                                |
| `date` (deprecated)              | -                                |
| -                                | `measured_at`                    |
| `weight`                         | `weight_kilogram`                |
| `fat`                            | `fat_mass_percentage`            |
| `water_percentage`               | `water_percentage`               |
| `muscle_mass_percentage`         | `muscle_mass_percentage`         |
| `visceral_fat_index`             | `visceral_fat_index`             |
| `bone_mass_percentage`           | `bone_mass_percentage`           |
| `body_mass_index`                | `body_mass_index`                |
| `lean_body_mass_kilogram`        | `lean_body_mass_kilogram`        |
| `waist_circumference_centimeter` | `waist_circumference_centimeter` |
| -                                | `time_zone`                      |
| `source.slug`                    | `source_provider`                |
| `source.type`                    | `source_type`                    |
| `source.device_id`               | `source_device_id`               |
| `source.app_id`                  | `source_app_id`                  |

#### Meal

| Meal field                         | Query Column                 |
| ---------------------------------- | ---------------------------- |
| `timestamp`                        | `index`                      |
| `name`                             | `name`                       |
| `energy.value`                     | `calories`                   |
| `macros.carbs`                     | `carbohydrate_gram`          |
| `macros.protein`                   | `protein_gram`               |
| `macros.alcohol`                   | `alcohol_gram`               |
| `macros.water`                     | `water_gram`                 |
| `macros.fibre`                     | `fibre_gram`                 |
| `macros.sugar`                     | `sugar_gram`                 |
| `macros.cholesterol`               | `cholesterol_gram`           |
| `macros.fats.saturated`            | `saturated_fat_gram`         |
| `macros.fats.monounsaturated`      | `monounsaturated_fat_gram`   |
| `macros.fats.polyunsaturated`      | `polyunsaturated_fat_gram`   |
| `macros.fats.omega3`               | `omega3_fat_gram`            |
| `macros.fats.omega6`               | `omega6_fat_gram`            |
| `macros.fats.total`                | `total_fat_gram`             |
| `micros.minerals.sodium`           | `sodium_milligram`           |
| `micros.minerals.potassium`        | `potassium_milligram`        |
| `micros.minerals.calcium`          | `calcium_milligram`          |
| `micros.minerals.phosphorus`       | `phosphorus_milligram`       |
| `micros.minerals.magnesium`        | `magnesium_milligram`        |
| `micros.minerals.iron`             | `iron_milligram`             |
| `micros.minerals.zinc`             | `zinc_milligram`             |
| `micros.minerals.fluoride`         | `fluoride_milligram`         |
| `micros.minerals.chloride`         | `chloride_milligram`         |
| `micros.vitamins.vitamin_a`        | `vitamin_a_milligram`        |
| `micros.vitamins.vitamin_b1`       | `vitamin_b1_milligram`       |
| `micros.vitamins.riboflavin`       | `riboflavin_milligram`       |
| `micros.vitamins.niacin`           | `niacin_milligram`           |
| `micros.vitamins.pantothenic_acid` | `pantothenic_acid_milligram` |
| `micros.vitamins.vitamin_b6`       | `vitamin_b6_milligram`       |
| `micros.vitamins.biotin`           | `biotin_microgram`           |
| `micros.vitamins.vitamin_b12`      | `vitamin_b12_microgram`      |
| `micros.vitamins.vitamin_c`        | `vitamin_c_milligram`        |
| `micros.vitamins.vitamin_d`        | `vitamin_d_microgram`        |
| `micros.vitamins.vitamin_e`        | `vitamin_e_milligram`        |
| `micros.vitamins.vitamin_k`        | `vitamin_k_microgram`        |
| `micros.vitamins.folic_acid`       | `folic_acid_microgram`       |
| `micros.trace_elements.chromium`   | `chromium_microgram`         |
| `micros.trace_elements.copper`     | `copper_milligram`           |
| `micros.trace_elements.iodine`     | `iodine_microgram`           |
| `micros.trace_elements.manganese`  | `manganese_milligram`        |
| `micros.trace_elements.molybdenum` | `molybdenum_microgram`       |
| `micros.trace_elements.selenium`   | `selenium_microgram`         |
| `source.slug`                      | `source_provider`            |
| `source.type`                      | `source_type`                |
| `source.app_id`                    | `source_app_id`              |
| `source.device_id`                 | `source_device_id`           |

#### MenstrualCycle

| MenstrualCycle field      | Query Column              | Element type                             |
| ------------------------- | ------------------------- | ---------------------------------------- |
| `period_start`            | `period_start`            | scalar (Date)                            |
| `period_end`              | `period_end`              | scalar (Date)                            |
| `cycle_end`               | `cycle_end`               | scalar (Date)                            |
| `is_predicted`            | `is_predicted`            | scalar (Boolean)                         |
| `menstrual_flow`          | `menstrual_flow`          | list of struct `{date, flow}`            |
| `cervical_mucus`          | `cervical_mucus`          | list of struct `{date, quality}`         |
| `intermenstrual_bleeding` | `intermenstrual_bleeding` | list of struct `{date}`                  |
| `contraceptive`           | `contraceptive`           | list of struct `{date, type}`            |
| `detected_deviations`     | `detected_deviations`     | list of struct `{date, deviation}`       |
| `ovulation_test`          | `ovulation_test`          | list of struct `{date, test_result}`     |
| `home_pregnancy_test`     | `home_pregnancy_test`     | list of struct `{date, test_result}`     |
| `home_progesterone_test`  | `home_progesterone_test`  | list of struct `{date, test_result}`     |
| `sexual_activity`         | `sexual_activity`         | list of struct `{date, protection_used}` |
| `basal_body_temperature`  | `basal_body_temperature`  | list of struct `{date, value}`           |
| `source.slug`             | `source_provider`         | scalar                                   |
| `source.type`             | `source_type`             | scalar                                   |
| `source.device_id`        | `source_device_id`        | scalar                                   |
| `source.app_id`           | `source_app_id`           | scalar                                   |

<Note>
  List columns cannot be selected directly as a table column — aggregate them with a scalar-output subquery. See [List-column aggregation](/sense/query-dsl/list-column-aggregation) for the full syntax.
</Note>

#### Profile

| Profile field      | Query Column        |
| ------------------ | ------------------- |
| `sex`              | `sex`               |
| `gender`           | `gender`            |
| `height`           | `height_centimeter` |
| `wheelchair_use`   | `wheelchair_use`    |
| `birth_date`       | `birth_date`        |
| `created_at`       | `created_at`        |
| `updated_at`       | `updated_at`        |
| `source.slug`      | `source_provider`   |
| `source.type`      | `source_type`       |
| `source.app_id`    | `source_app_id`     |
| `source.device_id` | `source_device_id`  |

### Timeseries

| Table                      | Python DSL                         | JSON DSL                                |
| -------------------------- | ---------------------------------- | --------------------------------------- |
| Timeseries Resource fields | `Timeseries.col("$1").field("$2")` | `{ "timeseries": "$1", "field": "$2" }` |

## Source Column expression

You can use a Source Column expression to refer to Data Source fields common to Junction resources.

Note that some Source Column expressions may not be valid in the implicit query context. For example, `source_sport` is not a valid Source Column
expression in a query that is selecting from the Sleep resource.

<Note>
  If both the *Provider* and *Source Type* Source Columns are present in the [Group By clause](/sense/query-dsl/group-by-clause),
  the implicit [Data Prioritization](/sense/data-prioritization) behavior would be disabled.
</Note>

| Column        | Python DSL                        | JSON DSL                            | Available in                   |
| ------------- | --------------------------------- | ----------------------------------- | ------------------------------ |
| Provider      | `Source.col("source_provider")`   | `{ "source": "source_provider" }`   | All Tables                     |
| Source Type   | `Source.col("source_type")`       | `{ "source": "source_type" }`       | All Tables                     |
| Source App ID | `Source.col("source_app_id")`     | `{ "source": "source_app_id" }`     | All summary tables             |
| Workout ID    | `Source.col("source_workout_id")` | `{ "source": "source_workout_id" }` | Workout Stream timeseries only |
| Sport         | `Source.col("source_sport")`      | `{ "source": "source_sport" }`      | Workout Stream timeseries only |

## Index Column expression

Each Junction resource has a primary datetime index. Your Query Instruction can reference this datetime
index using the special Index Column expression:

| Table                                     | Index                     | Python DSL                 | JSON DSL                           |
| ----------------------------------------- | ------------------------- | -------------------------- | ---------------------------------- |
| Activity daily summary<br />`activity`    | Calendar date             | `Activity.index()`         | `{ "index": "activity" }`          |
| Body summary<br />`body`                  | Measurement datetime      | `Body.index()`             | `{ "index": "body" }`              |
| Sleep summary<br />`sleep`                | Session end datetime      | `Sleep.index()`            | `{ "index": "sleep" }`             |
| Readiness scores<br />`derived_readiness` | Calendar date             | `DerivedReadiness.index()` | `{ "index": "derived_readiness" }` |
| Workout summary<br />`workout`            | Session start datetime    | `Workout.index()`          | `{ "index": "workout" }`           |
| Menstrual cycle<br />`menstrual_cycle`    | Period start date         | `MenstrualCycle.index()`   | `{ "index": "menstrual_cycle" }`   |
| Profile<br />`profile`                    | Updated At (UTC) datetime | `Profile.index()`          | `{ "index": "profile" }`           |

## Group Key Column expression

When your Query Instruction uses [the `group_by` clause](/sense/query-dsl/group-by-clause), each expression
in the `group_by` clause creates a temporary Group Key Column (`group_key.$OFFSET`). These temporary columns are then used to
facilitate the data grouping and aggregation as specified by your Query Instruction.

You can refer to these columns using the special Group Key Column expression:

| Group Key Columns | Python DSL       | JSON DSL               |
| ----------------- | ---------------- | ---------------------- |
| All               | `group_key("*")` | `{ "group_key": "*" }` |
| The `$N`-th key   | `group_key($N)`  | `{ "group_key": $N }`  |