This branch was auto-updated!

website/docs/docs/dbt-cloud-apis/sl-graphql.md

@@ -219,6 +219,8 @@ DimensionType = [CATEGORICAL, TIME]
 
 ### Querying
 
+When querying for data, _either_ a `groupBy` _or_ a `metrics` selection is required. 
+
 **Create Dimension Values query**
 
 ```graphql
@@ -443,29 +445,91 @@ mutation {
 }
 ```
 
+**Query a categorical dimension on its own**
+
+```graphql
+mutation {
+  createQuery(
+    environmentId: 123456
+    groupBy: [{name: "customer__customer_type"}]
+  ) {
+    queryId
+  }
+}
+```
+
 **Query with a where filter** 
 
 The `where` filter takes a list argument (or a string for a single input). Depending on the object you are filtering, there are a couple of parameters:
 
- - `Dimension()` — Used for any categorical or time dimensions. If used for a time dimension, granularity is required. For example, `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`.
+ - `Dimension()` — Used for any categorical or time dimensions. For example, `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`.
 
 - `Entity()` — Used for entities like primary and foreign keys, such as `Entity('order_id')`.
 
-Note: If you prefer a more strongly typed `where` clause, you can optionally use `TimeDimension()` to separate out categorical dimensions from time ones. The `TimeDimension` input takes the time dimension name and also requires granularity. For example, `TimeDimension('metric_time', 'MONTH')`.
+Note: If you prefer a `where` clause with a more explicit path, you can optionally use `TimeDimension()` to separate categorical dimensions from time ones. The `TimeDimension` input takes the time dimension and optionally the granularity level. `TimeDimension('metric_time', 'month')`.
 
 ```graphql
 mutation {
   createQuery(
     environmentId: BigInt!
     metrics:[{name: "order_total"}]
-    groupBy:[{name: "customer__customer_type"}, {name: "metric_time", grain: MONTH}]
+    groupBy:[{name: "customer__customer_type"}, {name: "metric_time", grain: month}]
     where:[{sql: "{{ Dimension('customer__customer_type') }} = 'new'"}, {sql:"{{ Dimension('metric_time').grain('month') }} > '2022-10-01'"}]
     ) {
      queryId
     }
 }
 ```
 
+For both `TimeDimension()`, the grain is only required in the WHERE filter if the aggregation time dimensions for the measures and metrics associated with the where filter have different grains. 
+
+For example, consider this Semantic model and Metric configuration, which contains two metrics that are aggregated across different time grains. This example shows a single semantic model, but the same goes for metrics across more than one semantic model.
+
+```yaml
+semantic_model:
+  name: my_model_source
+
+defaults:
+  agg_time_dimension: created_month
+  measures:
+    - name: measure_0
+      agg: sum
+    - name: measure_1
+      agg: sum
+      agg_time_dimension: order_year
+  dimensions:
+    - name: created_month
+      type: time
+      type_params:
+        time_granularity: month
+    - name: order_year
+      type: time
+      type_params:
+        time_granularity: year
+
+metrics:
+  - name: metric_0
+    description: A metric with a month grain.
+    type: simple
+    type_params:
+      measure: measure_0
+  - name: metric_1
+    description: A metric with a year grain.
+    type: simple
+    type_params:
+      measure: measure_1
+```
+
+Assuming the user is querying `metric_0` and `metric_1` together, a valid filter would be:
+
+  * `"{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"`
+
+Invalid filters would be:
+
+  * ` "{{ TimeDimension('metric_time') }} > '2020-01-01'"` — metrics in the query are defined based on measures with different grains.
+
+  * `"{{ TimeDimension('metric_time', 'month') }} > '2020-01-01'"` — `metric_1` is not available at a month grain.
+
 **Query with Order**
 
 ```graphql

website/docs/docs/dbt-cloud-apis/sl-jdbc.md

@@ -92,9 +92,9 @@ select * from {{
 
 <TabItem value="dimensionvalueformetrics" label="Fetch dimension values">
 
-Use this query to fetch dimension values for one or multiple metrics and single dimension. 
+Use this query to fetch dimension values for one or multiple metrics and a single dimension. 
 
-Note, `metrics` is a required argument that lists one or multiple metrics in it, and a single dimension. 
+Note, `metrics` is a required argument that lists one or multiple metrics, and a single dimension. 
 
 ```bash
 select * from {{ 
@@ -105,9 +105,9 @@ semantic_layer.dimension_values(metrics=['food_order_amount'], group_by=['custom
 
 <TabItem value="queryablegranularitiesformetrics" label="Fetch queryable granularities for metrics">
 
-Use this query to fetch queryable granularities for a list of metrics. This API request allows you to only show the time granularities that make sense for the primary time dimension of the metrics (such as `metric_time`), but if you want queryable granularities for other time dimensions, you can use the `dimensions()` call, and find the column queryable_granularities.
+You can use this query to fetch queryable granularities for a list of metrics. This API request allows you to only show the time granularities that make sense for the primary time dimension of the metrics (such as `metric_time`), but if you want queryable granularities for other time dimensions, you can use the `dimensions()` call, and find the column queryable_granularities.
 
-Note, `metrics` is a required argument that lists one or multiple metrics in it.
+Note, `metrics` is a required argument that lists one or multiple metrics.
 
 ```bash
 select * from {{
@@ -124,7 +124,7 @@ select * from {{
 
 Use this query to fetch available metrics given dimensions. This command is essentially the opposite of getting dimensions given a list of metrics.
 
-Note, `group_by` is a required argument that lists one or multiple dimensions in it.
+Note, `group_by` is a required argument that lists one or multiple dimensions.
 
 ```bash
 select * from {{
@@ -137,7 +137,7 @@ select * from {{
 
 <TabItem value="queryablegranularitiesalltimedimensions" label="Fetch queryable granularities for all time dimensions">
 
-Use this example query to fetch available granularities for all time dimesensions (the similar queryable granularities API call only returns granularities for the primary time dimensions for metrics). The following call is a derivative of the `dimensions()` call and specifically selects the granularities field.
+You can use this example query to fetch available granularities for all time dimensions (the similar queryable granularities API call only returns granularities for the primary time dimensions for metrics). The following call is a derivative of the `dimensions()` call and specifically selects the granularity field.
 
 ```bash
 select NAME, QUERYABLE_GRANULARITIES from {{
@@ -179,8 +179,6 @@ To query metric values, here are the following parameters that are available. Yo
 |`order`  | Order the data returned by a particular field     | `order_by=['order_gross_profit']`, use `-` for descending, or full object notation if the object is operated on: `order_by=[Metric('order_gross_profit').descending(True)`]   | 
 | `compile`   | If true, returns generated SQL for the data platform but does not execute | `compile=True`  | 
 
-
-
 ## Note on time dimensions and `metric_time`
 
 You will notice that in the list of dimensions for all metrics, there is a dimension called `metric_time`. `Metric_time` is a reserved keyword for the measure-specific aggregation time dimensions. For any time-series metric, the `metric_time` keyword should always be available for use in queries. This is a common dimension across *all* metrics in a semantic graph. 
@@ -266,11 +264,62 @@ Where filters in API allow for a filter list or string. We recommend using the f
 
 Where Filters have a few objects that you can use:
 
-- `Dimension()` - Used for any categorical or time dimensions. If used for a time dimension, granularity is required -  `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`
+- `Dimension()` &mdash; Used for any categorical or time dimensions. `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`.
+
+- `TimeDimension()` &mdash;  Used as a more explicit definition for time dimensions, optionally takes in a granularity `TimeDimension('metric_time', 'month')`.
+
+- `Entity()` &mdash;  Used for entities like primary and foreign keys - `Entity('order_id')`.
+
+
+For `TimeDimension()`, the grain is only required in the `WHERE` filter if the aggregation time dimensions for the measures and metrics associated with the where filter have different grains. 
+
+For example, consider this Semantic model and Metric config, which contains two metrics that are aggregated across different time grains. This example shows a single semantic model, but the same goes for metrics across more than one semantic model.
+
+```yaml
+semantic_model:
+  name: my_model_source
+
+defaults:
+  agg_time_dimension: created_month
+  measures:
+    - name: measure_0
+      agg: sum
+    - name: measure_1
+      agg: sum
+      agg_time_dimension: order_year
+  dimensions:
+    - name: created_month
+      type: time
+      type_params:
+        time_granularity: month
+    - name: order_year
+      type: time
+      type_params:
+        time_granularity: year
+
+metrics:
+  - name: metric_0
+    description: A metric with a month grain.
+    type: simple
+    type_params:
+      measure: measure_0
+  - name: metric_1
+    description: A metric with a year grain.
+    type: simple
+    type_params:
+      measure: measure_1
+
+```
+
+Assuming the user is querying `metric_0` and `metric_1` together in a single request, a valid `WHERE` filter would be:
+
+  * `"{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"`
+
+Invalid filters would be:
 
-- `Entity()` - Used for entities like primary and foreign keys - `Entity('order_id')`
+  * `"{{ TimeDimension('metric_time') }} > '2020-01-01'"` &mdash; metrics in the query are defined based on measures with different grains.
 
-Note: If you prefer a more explicit path to create the `where` clause, you can optionally use the `TimeDimension` feature. This helps separate out categorical dimensions from time-related ones. The `TimeDimesion` input takes the time dimension name and also requires granularity, like this: `TimeDimension('metric_time', 'MONTH')`.
+  * `"{{ TimeDimension('metric_time', 'month') }} > '2020-01-01'"` &mdash; `metric_1` is not available at a month grain.
 
 
 - Use the following example to query using a `where` filter with the string format:
@@ -295,18 +344,19 @@ where=["{{ Dimension('metric_time').grain('month') }} >= '2017-03-09'", "{{ Dime
 
 ### Query with a limit
 
-Use the following example to query using a `limit` or `order_by` clauses:
+Use the following example to query using a `limit` or `order_by` clause:
 
 ```bash
 select * from {{
 semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
   group_by=[Dimension('metric_time')],
   limit=10)
   }}
-``` 
+```
+
 ### Query with Order By Examples 
 
-Order By can take a basic string that's a Dimension, Metric, or Entity and this will default to ascending order
+Order By can take a basic string that's a Dimension, Metric, or Entity, and this will default to ascending order
 
 ```bash
 select * from {{
@@ -317,7 +367,7 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
   }}
 ``` 
 
-For descending order, you can add a `-` sign in front of the object. However, you can only use this short hand notation if you aren't operating on the object or using the full object notation. 
+For descending order, you can add a `-` sign in front of the object. However, you can only use this short-hand notation if you aren't operating on the object or using the full object notation. 
 
 ```bash
 select * from {{
@@ -326,8 +376,9 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
   limit=10,
   order_by=[-'order_gross_profit']
   }}
-``` 
-If you are ordering by an object that's been operated on (e.g., change granularity), or you are using the full object notation, descending order must look like:
+```
+
+If you are ordering by an object that's been operated on (for example, you changed the granularity of the time dimension), or you are using the full object notation, descending order must look like:
 
 ```bash
 select * from {{
@@ -366,14 +417,24 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
 
 <FAQ path="Troubleshooting/sl-alpn-error" />
 
-- **Why do some dimensions use different syntax, like `metric_time` versus `[Dimension('metric_time')`?**<br />
-	When you select a dimension on its own, such as `metric_time` you can use the shorthand method which doesn't need the “Dimension” syntax. However, when you perform operations on the dimension, such as adding granularity, the object syntax `[Dimension('metric_time')` is required. 
+<detailsToggle alt_header="Why do some dimensions use different syntax, like `metric_time` versus `Dimension('metric_time')`?">
+When you select a dimension on its own, such as `metric_time` you can use the shorthand method which doesn't need the “Dimension” syntax. 
+
+However, when you perform operations on the dimension, such as adding granularity, the object syntax `[Dimension('metric_time')` is required.
+</detailsToggle>
+
+<detailsToggle alt_header="What does the double underscore `'__'` syntax in dimensions mean?">
+
+The double underscore `"__"` syntax indicates a mapping from an entity to a dimension, as well as where the dimension is located. For example, `user__country` means someone is looking at the `country` dimension from the `user` table.
+</detailsToggle>
+
+<detailsToggle alt_header="What is the default output when adding granularity?">
+
+The default output follows the format `{{time_dimension_name}__{granularity_level}}`. 
 
-- **What does the double underscore `"__"` syntax in dimensions mean?**<br />
-	The double underscore `"__"` syntax indicates a mapping from an entity to a dimension, as well as where the dimension is located. For example, `user__country` means someone is looking at the `country` dimension from the `user` table.
+So for example, if the `time_dimension_name` is `ds` and the granularity level is yearly, the output is `ds__year`.
 
-- **What is the default output when adding granularity?**<br />
-	The default output follows the format `{time_dimension_name}__{granularity_level}`. So for example, if the time dimension name is `ds` and the granularity level is yearly, the output is `ds__year`.
+</detailsToggle>
 
 ## Related docs