Update sl-jdbc.md

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

@@ -432,25 +432,83 @@ mutation {
 
 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 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 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()` and `Dimension()` objects, 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

@@ -254,11 +254,70 @@ 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')`
 
 - `Entity()` - Used for entities like primary and foreign keys - `Entity('order_id')`
 
-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')`.
+
+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 `TimeDimension` input takes the time dimension name optionally requires granularity, like this: `TimeDimension('metric_time', 'month')`.
+
+For both `TimeDimension()` and `Dimension()` objects, the grain is only required if 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 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:
+
+  `* "{{ 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:
@@ -315,7 +374,7 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
   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 (e.g., 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 {{