Add API updates

spiceai · Nov 28, 2024 · 2c9bc9a · 2c9bc9a
1 parent a9451e6
commit 2c9bc9a
Show file tree

Hide file tree

Showing 13 changed files with 227 additions and 225 deletions.
diff --git a/spiceaidocs/docs/acknowledgements/index.md b/spiceaidocs/docs/acknowledgements/index.md
diff --git a/spiceaidocs/docs/api/adbc/index.md b/spiceaidocs/docs/api/adbc/index.md
@@ -17,7 +17,7 @@ Get started with ADBC using Python.
 
 ### Installation
 
-Start Python Envionment.
+Start a Python environment.
 
 ```shell
 python

diff --git a/spiceaidocs/docs/api/arrow-flight-sql/index.md b/spiceaidocs/docs/api/arrow-flight-sql/index.md
@@ -7,10 +7,10 @@ description: 'Query Spice using JDBC/ODBC/ADBC'
 
 [Arrow Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html) is a protocol for interacting with SQL databases using the Arrow in-memory format and the Flight RPC framework.
 
-Spice implements the Flight SQL protocol which enables querying the datasets configured in Spice via tools that support connecting via one of the Arrow Flight SQL drivers, such as [DBeaver](https://dbeaver.io), [Tableau](https://www.tableau.com/), or [Power BI](https://www.microsoft.com/en-us/power-platform/products/power-bi).
+Spice implements the Flight SQL protocol, enabling querying of the datasets configured in Spice via tools that support connecting via one of the Arrow Flight SQL drivers, such as [DBeaver](https://dbeaver.io), [Tableau](https://www.tableau.com/), or [Power BI](https://www.microsoft.com/en-us/power-platform/products/power-bi).
 
 <img src="https://imagedelivery.net/HyTs22ttunfIlvyd6vumhQ/0a8bc474-03c3-4c1c-8003-d250cd52b300/public" alt="arrow flight and spice" />
 
 ## Authentication
 
-API Key authentication is supported for the Arrow Flight SQL endpoint. See [API Key Authentication](../../api/auth/index.md) for more details.
+API Key authentication is supported for the Arrow Flight SQL endpoint. For more details, see [API Key Authentication](../../api/auth/index.md).
diff --git a/spiceaidocs/docs/api/http/catalogs.md b/spiceaidocs/docs/api/http/catalogs.md
@@ -5,9 +5,9 @@ description: 'Fetch catalogs'
 sidebar_position: 5
 ---
 
-Returns the list of configured [catalogs](/components/catalogs)
+The `GET /v1/catalogs` endpoint returns a list of configured catalogs.
 
-Example:
+Example request:
 
 ```bash
 curl --request GET \

diff --git a/spiceaidocs/docs/api/http/chat-completions.md b/spiceaidocs/docs/api/http/chat-completions.md
@@ -5,7 +5,7 @@ description: ''
 sidebar_position: 6
 ---
 
-Chat completions is an OpenAI compatible endpoint.
+The `POST /v1/chat/completions` endpoint is an OpenAI compatible endpoint for generating chat completions.
 
 Specify the model by providing the component name in the `model` key. For example:
 

diff --git a/spiceaidocs/docs/api/http/datasets.md b/spiceaidocs/docs/api/http/datasets.md
@@ -5,9 +5,9 @@ description: 'Fetch datasets'
 sidebar_position: 2
 ---
 
-Returns a the list of configured datasets.
+The `GET /v1/datasets` endpoint returns a list of configured datasets.
 
-Example:
+Example request:
 
 ```bash
 curl --request GET \

diff --git a/spiceaidocs/docs/api/http/embeddings.md b/spiceaidocs/docs/api/http/embeddings.md
@@ -5,7 +5,7 @@ description: ''
 sidebar_position: 7
 ---
 
-Chat completions is an OpenAI compatible endpoint.
+The `POST /v1/embeddings` endpoint is an OpenAI compatible endpoint for generating embeddings.
 
 Specify the embedding model by providing the component name in the `model` key. For example:
 

diff --git a/spiceaidocs/docs/api/http/index.md b/spiceaidocs/docs/api/http/index.md
@@ -13,11 +13,11 @@ import DocCardList from '@theme/DocCardList';
 
 ## Authentication
 
-API Key authentication is supported for all HTTP routes. See [API Key Authentication](../../api/auth/index.md) for more details.
+API Key authentication is supported for all HTTP routes. For more details, see [API Key Authentication](../../api/auth/index.md).
 
 ## Cross-Origin Resource Sharing (CORS)
 
-CORS is disabled by default. Enable for all origins with:
+CORS is disabled by default. To enable CORS for all origins, add the following configuration to your `spicepod.yaml` file:
 
 ```yaml
 runtime:

diff --git a/spiceaidocs/docs/api/http/ml-predict.md b/spiceaidocs/docs/api/http/ml-predict.md
@@ -8,9 +8,9 @@ sidebar_position: 10
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Make predictions using all loaded forecasting models in parallel, useful for ensembling or A/B testing.
+The `POST /v1/predict` endpoint is used to make predictions using all loaded forecasting models in parallel. This is useful for ensembling or A/B testing different models.
 
-Example:
+Example request:
 
 ```shell
 curl --request POST \

diff --git a/spiceaidocs/docs/api/http/refresh.md b/spiceaidocs/docs/api/http/refresh.md
@@ -10,10 +10,11 @@ pagination_next: null
 Performs an on-demand refresh for an accelerated dataset. On-demand refresh applies only to `full` and `append` refresh modes (not `changes`).
 
 Request Body:
- - `refresh_sql` (String, Optional): Refresh SQL to use, see [Refresh SQL docs](/components/data-accelerators/data-refresh.md#refresh-sql). Defaults to the `refresh_sql` specified in the spicepod.
- - `refresh_mode` (String, Optional): Refresh mode to use, see [Refresh Modes docs](/components/data-accelerators/data-refresh.md#refresh-modes). Defaults to `refresh_mode` specified in the spicepod.
 
- Example:
+- `refresh_sql` (String, Optional): Refresh SQL to use, see [Refresh SQL docs](/components/data-accelerators/data-refresh.md#refresh-sql). Defaults to the `refresh_sql` specified in the spicepod.
+- `refresh_mode` (String, Optional): Refresh mode to use, see [Refresh Modes docs](/components/data-accelerators/data-refresh.md#refresh-modes). Defaults to `refresh_mode` specified in the spicepod.
+
+Example:
 
 ```bash
 curl -i -XPOST 127.0.0.1:8090/v1/datasets/taxi_trips/acceleration/refresh \

diff --git a/spiceaidocs/docs/api/http/search.md b/spiceaidocs/docs/api/http/search.md
@@ -10,15 +10,17 @@ pagination_next: null
 Performs a basic vector similarity search across one or more datasets.
 
 Request Body
- - `datasets` (array of strings, Optional): Names of the dataset components to perform the similarity search on. Each dataset must have exactly one column augmented with an embedding. If None, all available datasets are used.
- - `text` (string): Query plaintext used to retrieve similar rows from the underlying datasets listed in the `from` request key.
- - `limit` (integer): The number of rows to return, per `from` dataset. Default: 3.
- - `where` (string): An SQL filter predicate to apply within the search.
- - `additional_columns` (array of strings): Additional columns, from the datasets, to return in the response (under `.matches[*].metadata`).
+
+- `datasets` (array of strings, Optional): Names of the dataset components to perform the similarity search on. Each dataset must have exactly one column augmented with an embedding. If None, all available datasets are used.
+- `text` (string): Query plaintext used to retrieve similar rows from the underlying datasets listed in the `from` request key.
+- `limit` (integer): The number of rows to return, per `from` dataset. Default: 3.
+- `where` (string): An SQL filter predicate to apply within the search.
+- `additional_columns` (array of strings): Additional columns, from the datasets, to return in the response (under `.matches[*].metadata`).
 
 #### Example
 
 Spicepod
+
 ```yaml
 embeddings:
   - name: embedding_maker
@@ -34,6 +36,7 @@ datasets:
 ```
 
 Request
+
 ```shell
 curl -XPOST http://localhost:3000/v1/search \
   -d '{
@@ -46,27 +49,30 @@ curl -XPOST http://localhost:3000/v1/search \
 ```
 
 Response
+
 ```json
 {
-  "matches": [{
-    "value": "I booked use some tickets",
-    "dataset": "app_messages",
-    "primary_key": {"id": "6fd5a215-0881-421d-ace0-b293b83452b5"},
-    "metadata": {"timestamp": 1724716542}
-   },
-   {
-    "value": "direct to Narata",
-    "dataset": "app_messages",
-    "primary_key": {"id": "8a25595f-99fb-4404-8c82-e1046d8f4c4b"},
-    "metadata": {"timestamp": 1724715881}
-   },
-   {
-    "value": "Yes, we're sitting together",
-    "dataset": "app_messages",
-    "primary_key": {"id": "8421ed84-b86d-4b10-b4da-7a432e8912c0"},
-    "metadata": {"timestamp": 1724716123}
-   }],
-  "duration_ms": 42,
+  "matches": [
+    {
+      "value": "I booked use some tickets",
+      "dataset": "app_messages",
+      "primary_key": { "id": "6fd5a215-0881-421d-ace0-b293b83452b5" },
+      "metadata": { "timestamp": 1724716542 }
+    },
+    {
+      "value": "direct to Narata",
+      "dataset": "app_messages",
+      "primary_key": { "id": "8a25595f-99fb-4404-8c82-e1046d8f4c4b" },
+      "metadata": { "timestamp": 1724715881 }
+    },
+    {
+      "value": "Yes, we're sitting together",
+      "dataset": "app_messages",
+      "primary_key": { "id": "8421ed84-b86d-4b10-b4da-7a432e8912c0" },
+      "metadata": { "timestamp": 1724716123 }
+    }
+  ],
+  "duration_ms": 42
 }
 ```
 

diff --git a/spiceaidocs/docs/api/jdbc/index.md b/spiceaidocs/docs/api/jdbc/index.md
@@ -16,17 +16,14 @@ Spice supports JDBC clients through a JDBC driver implementation based on the [F
 ### Download the Flight SQL JDBC driver
 
 - Find the appropriate [Flight SQL JDBC driver](https://central.sonatype.com/artifact/org.apache.arrow/flight-sql-jdbc-driver/versions) version.
-- Click **Browse**  next to the version you want to download
+- Click **Browse** next to the version you want to download
 - Click the `flight-sql-jdbc-driver-XX.XX.XX.jar` file (with only the `.jar` file extension) from the list of files to download the driver jar file
 
 ### Add the driver to your application
 
 Follow the instructions specific to your application for adding a custom JDBC driver. Examples:
 
-**Tableau**:
-    - Windows: `C:\Program Files\Tableau\Drivers`
-    - Mac: `~/Library/Tableau/Drivers`
-    - Linux: `/opt/tableau/tableau_driver/jdbc` - Start or restart Tableau
+**Tableau**: - Windows: `C:\Program Files\Tableau\Drivers` - Mac: `~/Library/Tableau/Drivers` - Linux: `/opt/tableau/tableau_driver/jdbc` - Start or restart Tableau
 
 [Full instruction](/clients/tableau)
 
@@ -51,8 +48,8 @@ Follow the instructions specific to your application for adding a custom JDBC dr
 - **URL**: `jdbc:arrow-flight-sql://{host}:{port}`
 - **Dialect**: `PostgreSQL`
 
- For example:
- <img width="400" src="/img/tableau/tableau-jdbc-conn.png"/>
+For example:
+<img width="400" src="/img/tableau/tableau-jdbc-conn.png"/>
 
 1. **Ensure Spice is running**
 1. Click **Connect**
@@ -75,4 +72,4 @@ Replace `<enter-api-key-here>` with the API key value. The `user` and `password`
 
 In the configured application, run a sample query, such as `SELECT * FROM taxi_trips;`
 
-![Query Results](https://imagedelivery.net/HyTs22ttunfIlvyd6vumhQ/0e9f3c0f-2e03-47f9-8d5e-65e078d7e900/public "Query Results")
+![Query Results](https://imagedelivery.net/HyTs22ttunfIlvyd6vumhQ/0e9f3c0f-2e03-47f9-8d5e-65e078d7e900/public 'Query Results')
diff --git a/spiceaidocs/docs/api/odbc/index.md b/spiceaidocs/docs/api/odbc/index.md
@@ -81,14 +81,14 @@ Spice supports ODBC clients through an ODBC driver implementation based on the [
 
 ### ODBC Connection Parameters
 
-| Name | Type | Description |
-|-|-|-|
-| host | string | The IP address or hostname for the Spice runtime. |
-| port | integer | The Spice runtime Arrow Flight endpoint port number |
-| useEncryption  | integer | Configures the driver to use an SSL-encrypted connection. Accepted values: `true` (default) - The client communicates with the Spice runtime only using SSL encryption and `false` - SSL encryption is disabled. |
-| disableCertificateVerification | integer | Specifies whether the driver should verify the host certificate against the trust store. Default is `false`|
-| useSystemTrustStore | integer | Controls whether to use a CA certificate from the system's trust store, or from a specified .pem file. If `true` - The driver verifies the connection using a certificate in the system trust store. IF `false` - The driver verifies the connection using the .pem file specified by the `trustedCerts` parameter. `true` on Windows and macOS, `false` on Linux by default |
-| trustedCerts | string  | The full path of the .pem file containing certificates trusted by a CA, for the purpose of verifying the server. If this option is not set, then the driver defaults to using the trusted CA certificates .pem file installed by the driver. |
+| Name                           | Type    | Description                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| host                           | string  | The IP address or hostname for the Spice runtime.                                                                                                                                                                                                                                                                                                                            |
+| port                           | integer | The Spice runtime Arrow Flight endpoint port number                                                                                                                                                                                                                                                                                                                          |
+| useEncryption                  | integer | Configures the driver to use an SSL-encrypted connection. Accepted values: `true` (default) - The client communicates with the Spice runtime only using SSL encryption and `false` - SSL encryption is disabled.                                                                                                                                                             |
+| disableCertificateVerification | integer | Specifies whether the driver should verify the host certificate against the trust store. Default is `false`                                                                                                                                                                                                                                                                  |
+| useSystemTrustStore            | integer | Controls whether to use a CA certificate from the system's trust store, or from a specified .pem file. If `true` - The driver verifies the connection using a certificate in the system trust store. IF `false` - The driver verifies the connection using the .pem file specified by the `trustedCerts` parameter. `true` on Windows and macOS, `false` on Linux by default |
+| trustedCerts                   | string  | The full path of the .pem file containing certificates trusted by a CA, for the purpose of verifying the server. If this option is not set, then the driver defaults to using the trusted CA certificates .pem file installed by the driver.                                                                                                                                 |
 
 :::note
 The ODBC driver for Arrow Flight SQL does not support password-protected `.pem/.crt` files or multiple `.crt` certificates in a single `.pem/.crt` file.