# Apache Arrow Flight API

Query Spice Cloud with SQL over the Apache Arrow Flight API (gRPC) and fetch large results with the Spice SDKs or pyarrow.

SQL query results can be served via a high-performance [Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html) endpoint. Arrow Flight uses the [gRPC](https://grpc.io/) protocol for efficient data transfer.

This setup enables high-speed access to your data in [Python](https://arrow.apache.org/docs/python/index.html), [Go](https://pkg.go.dev/github.com/apache/arrow/go/v8), [C++](https://arrow.apache.org/docs/cpp/index.html), [C#](https://github.com/apache/arrow-dotnet), [Rust](https://docs.rs/arrow-flight/latest/arrow_flight/), and [Java](https://arrow.apache.org/java/) and makes it easy to use libraries like [Pandas](https://arrow.apache.org/docs/python/pandas.html) and [NumPy](https://arrow.apache.org/docs/python/numpy.html?highlight=numpy).

## SDKs

It's recommended to use the Spice.ai SDKs to connect and query the Arrow Flight endpoint. SDKs are available for [Python](https://spice.ai/docs/sdks/python-sdk), [Node.js](https://spice.ai/docs/sdks/node.js-sdk), [Go](https://spice.ai/docs/sdks/go), [Rust](https://spice.ai/docs/sdks/rust-sdk), [Java](https://spice.ai/docs/sdks/java-sdk), and [Dotnet](https://spice.ai/docs/sdks/dotnet-sdk).

In Python, query results can be easily converted to Pandas or NumPy formats.

You may also use Apache's `pyarrow` library directly.

## Connecting to the Endpoint

- Endpoint URL: `grpc+tls://flight.spiceai.io` for a project in `us-east-1`. For a project in another region or on a dedicated cluster, use the Flight host in the project's **Settings** > **Endpoints**.
- Basic Authentication:
  - Username can be set to an empty string
  - Password should be set to the API key of your project

### Requirements

- Table names must be fully-qualified. For example `spiceai.quickstart`

## Samples

Find Python code samples on the [Python SDK](https://spice.ai/docs/sdks/python-sdk) page.

## Troubleshooting

### Mac/Windows Certificate issue

If you get this error:

`Could not get default pem root certs`

Install the [Let's Encrypt root certificates](https://letsencrypt.org/certificates/).

****Instructions for macOS****

First download the `roots.pem` file from the Let's Encrypt server:

```bash
curl -Lo isrgrootx1.pem https://letsencrypt.org/certs/isrgrootx1.pem 
```

Before running your code/jupyter notebook the environment variable `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` must be set to the pem file path. If you are using command from a terminal this can be done from the folder containing `isrgrootx1.pem` with:

```bash
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="$PWD/isrgrootx1.pem"
```

The `export` command will set this variable for this specific terminal and thus will need to be run every time you open a new terminal. Additionally you can add to your terminal profile.

Note that `$PWD` is a bash-specific variable that will be replaced by the current directory path. You can download the certificate file `isrgrootx1.pem` in a specific location and inform this path instead of `$PWD`.

**Instructions for Windows**

```powershell
@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
    (new-object System.Net.WebClient).Downloadfile( ^
        'https://letsencrypt.org/certs/isrgrootx1.pem', 'isrgrootx1.pem')
set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\isrgrootx1.pem
```