Add Apache Arrow query endpoint documentation

- Added Arrow endpoint examples in getting-started.md
- Updated API reference with Arrow query format
- Added Arrow vs JSON performance benchmarks
- 7.36x faster for large result sets (100K+ rows)
- 43% smaller payloads

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Ignacio Van Droogenbroeck

docs/api-reference/overview.md

@@ -56,7 +56,7 @@ response = requests.post(
 )
 ```
 
-### Query Data
+### Query Data (JSON)
 
 ```bash
 curl -X POST http://localhost:8000/query \
@@ -65,6 +65,25 @@ curl -X POST http://localhost:8000/query \
   -d '{"sql": "SELECT * FROM cpu LIMIT 10"}'
 ```
 
+### Query Data (Apache Arrow)
+
+For large result sets, use Arrow format for 7.36x faster performance:
+
+```python
+import requests
+import pyarrow as pa
+
+response = requests.post(
+    "http://localhost:8000/query/arrow",
+    headers={"Authorization": "Bearer YOUR_TOKEN"},
+    json={"sql": "SELECT * FROM cpu LIMIT 100000"}
+)
+
+# Parse Arrow IPC stream
+reader = pa.ipc.open_stream(response.content)
+arrow_table = reader.read_all()
+```
+
 ### Health Check
 
 ```bash
@@ -87,7 +106,8 @@ High-performance data writing endpoints.
 
 Execute SQL queries with DuckDB.
 
-- **[Execute Query](/arc/api-reference/queries#execute)** - Run SQL queries
+- **[Execute Query](/arc/api-reference/queries#execute)** - Run SQL queries (JSON format)
+- **[Execute Query (Arrow)](/arc/api-reference/queries#arrow)** - Run SQL queries (Apache Arrow format)
 - **[Stream Results](/arc/api-reference/queries#stream)** - Stream large datasets
 - **[Query Estimation](/arc/api-reference/queries#estimate)** - Estimate query cost
 - **[List Measurements](/arc/api-reference/queries#list)** - Show available tables

docs/getting-started.md

@@ -225,6 +225,48 @@ response = requests.post(
 )
 ```
 
+### Apache Arrow Format (For Large Result Sets)
+
+For queries returning 10K+ rows, use the Apache Arrow endpoint for **7.36x faster performance** and **43% smaller payloads**.
+
+```python
+import requests
+import pyarrow as pa
+import pandas as pd
+import os
+
+token = os.getenv("ARC_TOKEN")
+
+# Query with Arrow format
+response = requests.post(
+    "http://localhost:8000/query/arrow",
+    headers={
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    },
+    json={
+        "sql": "SELECT * FROM cpu WHERE time > now() - INTERVAL '1 hour' LIMIT 10000"
+    }
+)
+
+# Parse Arrow IPC stream
+reader = pa.ipc.open_stream(response.content)
+arrow_table = reader.read_all()
+
+# Convert to Pandas (zero-copy)
+df = arrow_table.to_pandas()
+
+print(f"Rows: {len(df)}")
+print(df.head())
+```
+
+**Performance benefits:**
+- Zero-copy conversion to Pandas/Polars
+- Columnar format stays efficient end-to-end
+- Ideal for analytics notebooks and data pipelines
+
+See [Arc README examples](https://github.com/basekick-labs/arc#apache-arrow-columnar-queries) for Polars usage.
+
 ## Check Health
 
 ```bash

docs/performance/benchmarks.md

@@ -205,6 +205,35 @@ Arc achieves exceptional write throughput through MessagePack binary protocol.
 
 **MessagePack vs Line Protocol**: 8.4x faster
 
+## Query Format Performance
+
+Arc supports two query result formats: JSON and Apache Arrow.
+
+### Apache Arrow vs JSON Benchmarks
+
+| Result Size | JSON Time | Arrow Time | Speedup | Size Reduction |
+|-------------|-----------|------------|---------|----------------|
+| 1K rows | 0.0130s | 0.0099s | 1.31x | 42.8% smaller |
+| 10K rows | 0.0443s | 0.0271s | 1.63x | 43.4% smaller |
+| 100K rows | 0.3627s | 0.0493s | **7.36x** | 43.5% smaller |
+
+**Test Configuration**:
+- Hardware: Apple M3 Max
+- Query: `SELECT * FROM cpu LIMIT N`
+- Endpoints: `/query` (JSON) vs `/query/arrow` (Arrow IPC)
+
+**Key Findings**:
+- Arrow format is 7.36x faster for large result sets (100K+ rows)
+- Payloads are 43% smaller with Arrow
+- Zero-copy conversion to Pandas/Polars
+- Columnar format stays efficient end-to-end
+
+**When to use Arrow**:
+- Large result sets (10K+ rows)
+- Wide tables with many columns
+- Data pipelines feeding into Pandas/Polars
+- Analytics notebooks and dashboards
+
 ## Reproducibility
 
 All benchmarks are reproducible. See [Running Benchmarks](/arc/performance/running-benchmarks) for instructions.