Update sl-jdbc.md

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 out 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 & 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

@@ -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()` — Used for any categorical or time dimensions. `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`.
+
+- `TimeDimension()` —  Used as a more explicit definition for time dimensions, optionally takes in a granularity `TimeDimension('metric_time', 'month')`.
+
+- `Entity()` —  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:
 
-- `Entity()` - Used for entities like primary and foreign keys - `Entity('order_id')`
+  * `"{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"`
 
-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')`.
+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.
 
 
 - Use the following example to query using a `where` filter with the string format:
@@ -303,7 +352,8 @@ 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
@@ -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 the granularity of the time dimension), or you are using the full object notation, descending order must look like:
 
 ```bash
 select * from {{
@@ -364,16 +415,26 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
 
 ## FAQs
 
-<FAQ path="Troubleshooting/sl-alpn-error" />
+<FAQ path="Troubleshooting/sl-alpn-error" /><br />
+
+<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?">
 
-- **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. 
+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