docs(ai): adds value search section (#9020)

* docs(ai): adds value search section * deduplicates value search --------- Co-authored-by: Michael Irvine <[email protected]>
cube-js · Dec 16, 2024 · 59dc373 · 59dc373
1 parent 64104c5
commit 59dc373
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 0 deletions.
diff --git a/docs/pages/product/apis-integrations/ai-api.mdx b/docs/pages/product/apis-integrations/ai-api.mdx
@@ -181,6 +181,44 @@ to give the AI context on possible values in a categorical dimension:
               - completed
 ```
 
+### Value search
+
+By default, the AI API has no ability to see the contents of your data (for privacy reasons).
+However, this makes it difficult for the AI API to generate correct filters for some queries.
+
+Imagine you have a categorical `order_status` dimension with the possible values "shipped",
+"processing", and "completed". Without value search, asking "how many complete orders did
+we have today" might get you a query filtering on `order_status = 'Complete'` instead of
+the correct `order_status = 'completed'`.
+
+To solve this, the AI API can perform "value searches" where it introspects the values in
+selected categorical dimensions before running a query. Value search is opt-in and dimensions
+must be enabled for it individually. Currently, the AI API performs value search by running
+Cube queries using the `contains` filter operator against one or more chosen dimensions.
+The LLM will select dimensions from among those you have based on the question asked and
+generate possible values dynamically.
+
+<InfoBox>
+  When running value search queries, the AI API passes through the security context used
+  for the AI API request, so security is maintained and only dimensions the end user has
+  access to are able to be searched.
+</InfoBox>
+
+To enable value search on a dimension, set the `searchable` field to true under the `ai`
+meta tag, as shown below:
+```yaml
+    - name: order_status
+      sql: order_status
+      type: string
+      meta:
+        ai:
+          searchable: true
+```
+
+Note that enabling Value Search may lead to slightly longer AI API response times when it
+is used but should result in significantly more accurate queries in many situations. Value
+Search can only be used on string dimensions.
+
 ### Other LLM providers
 
 <InfoBox>

diff --git a/docs/pages/product/workspace/ai-assistant.mdx b/docs/pages/product/workspace/ai-assistant.mdx
@@ -97,6 +97,11 @@ to give the AI context on possible values in a categorical dimension:
               - completed
 ```
 
+### Value search
+
+Value Search can be enabled for AI Assistant in the same way as for the AI API. See the 
+[AI API's documentation][ref-ai-api-value-search] for details and instructions.
+
 ### Other LLM providers
 
 See the [AI API's documentation][ref-ai-api-providers] for information on how to "bring your own" LLM. 
@@ -127,3 +132,4 @@ See the [AI API's documentation][ref-ai-api-providers] for information on how to
 [ref-playground]: /product/workspace/playground
 [ref-catalog-downstream]: /product/workspace/semantic-catalog#connecting-downstream-tools
 [ref-ai-api-providers]: /product/apis-integrations/ai-api#other-llm-providers
+[ref-ai-api-value-search]: /product/apis-integrations/ai-api#value-search