feat(new): Add query observability feature to docs #362
Conversation
Several updates for this new feature including capabilities, console UI, release notes, and other misc updates.
✅ Deploy Preview for luxury-shortbread-acee05 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: Paul Wozniczka <25128922+pwoznic@users.noreply.github.com>
There was a problem hiding this comment.
@pwoznic some non-blocking suggestions. Overall the docs look great and most (all?) of my comments are very subjective 😄
| import {vars} from '@site/static/variables.json'; | ||
| import {Config} from '@site/docs/definitions.md'; | ||
|
|
||
| The List Query Histories API allows you to retrieve, update, and manage query |
There was a problem hiding this comment.
| The List Query Histories API allows you to retrieve, update, and manage query | |
| The List Query Histories API allows you to retrieve, update, and manage query |
Are we firm on this name? It sounds a bit odd to me. Could we consider: Query history API or Query history list API?
Non-blocking suggestion 😄
There was a problem hiding this comment.
Not sure if firm (we can run by team for sure), but FWIW I'm going by the yaml descriptions where one is for a specific query and the other is to list a group of multiple queries.
There was a problem hiding this comment.
FWIW CJ updated the console copy to say “query histories”
There was a problem hiding this comment.
I think that naming convention makes sense with a UI where there's more (visual) context, so this may be a non-issue if our users are familiar with the console/broader context of this.
I think if there's a standalone experience where a user comes across this API it may have some additional cognitive load to understand what exactly it means or does 🙂
| query performance, debugging individual queries, and retrieving detailed | ||
| information such as the call stack of a query execution. | ||
|
|
||
| ## List Query Histories Request and Response |
There was a problem hiding this comment.
This may just be a me thing today, but my brain doesn't grok this naming well.
To me even changing it to "List Query History" might resonate more than the plural "Histories". It's a nit, so I'm not firm here
There was a problem hiding this comment.
Same comment here: if consistency with the UI makes any difference, “Query Histories” is what we use in console.
what you said makes a lot of sense though, @omnomagonz
| To get a history of a specific query, send a GET request to | ||
| `/v2/queries`. You can specify the `corpus_key`, `chat_id`, and the | ||
| `limit` which is the maximum number of historical queries to list. The | ||
| response includes an array of query histories. |
There was a problem hiding this comment.
| response includes an array of query histories. | |
| response includes an array of previous queries. |
Non-blocking
| The Get Query History API allows you to retrieve detailed history about a | ||
| specific query that was made against a corpus. The response includes detailed |
There was a problem hiding this comment.
| The Get Query History API allows you to retrieve detailed history about a | |
| specific query that was made against a corpus. The response includes detailed | |
| The Get Query History API allows you to retrieve detailed history about a | |
| specific query that was made against a corpus. The response includes detailed |
This may be naming convention, so this is another non-blocking suggestion: could we consider changing this to be (imo) more distinct vs the other List Query Histories API? An alternative here could be: Query Analysis API or Single Query History API.
I think something that can help further differentiate between this single query history object and the other list of multiple queries object could be helpful
| generative response times, users can better understand how our system performs | ||
| relative to their business goals. |
There was a problem hiding this comment.
| generative response times, users can better understand how our system performs | |
| relative to their business goals. | |
| generative response times, users can better understand how to fine-tune Vectara to meet their business goals. |
non-blocking
| 1. Experiment with different query configurations by asking questions of | ||
| your data with **Send query**. |
There was a problem hiding this comment.
| 1. Experiment with different query configurations by asking questions of | |
| your data with **Send query**. | |
| 1. Ask questions of your data with **Send query**. |
Non-blocking.
This reads a bit odd to me. I think the intent here is to say: "First, submit a query", but it sort of jumps ahead with "experiment with different queries".
My mind is interpreting this as out of order. I think if we lead with "first, submit a query" and then maybe add a separate step of "use this information to optimize your configuration and submit a new query" this could help
| Click **Expand all** to reveal detailed information for each execution stage, | ||
| including specific parameters. | ||
|
|
||
| Select **Load into Query tab** to go back to query configuration so that you |
There was a problem hiding this comment.
This is a little unclear to me. How about something like “…to load this configuration into your query tab”?
It just reiterates the button text, but I think it may be clearer than saying “go back to query configuration”.
pwoznic
changed the title
Added documentation for the new query observability feature. This contains the long-form updates and the API reference updates will be next.