stately_arrow/
lib.rs

1//! Arrow-based data connectivity and query execution over HTTP APIs.
2//!
3//! This crate provides a flexible abstraction layer over `DataFusion` for building data query
4//! services with support for multiple backend connectors.
5//!
6//! # Terminology
7//!
8//! - **Connector**: The raw configuration for a data source (credentials, endpoints, options).
9//! - **Connection**: Runtime metadata about a connector's active presence in `DataFusion`,
10//!   including its catalog name and capabilities.
11//! - **Backend**: The implementation that bridges a connector configuration to `DataFusion`,
12//!   handling session setup and query execution.
13//!
14//! # Core Abstractions
15//!
16//! - [`ConnectorRegistry`]: Trait for managing and retrieving connectors by ID.
17//! - [`Backend`]: Trait for data source implementations that integrate with `DataFusion`.
18//! - [`QueryContext`]: High-level query execution interface combining a session and registry.
19//! - [`QuerySession`]: Abstraction over `DataFusion`'s `SessionContext` for custom implementations.
20//!
21//! # API Endpoints
22//!
23//! The [`api::router`] function provides these endpoints:
24//!
25//! | Method | Path | Description |
26//! |--------|------|-------------|
27//! | `GET` | `/connectors` | List available connectors |
28//! | `POST` | `/connectors` | Get details for multiple connectors |
29//! | `GET` | `/connectors/{id}` | Get connector details |
30//! | `GET` | `/register` | List registered connections |
31//! | `GET` | `/register/{id}` | Register a connector |
32//! | `GET` | `/catalogs` | List `DataFusion` catalogs |
33//! | `POST` | `/query` | Execute SQL query (streaming Arrow IPC) |
34//!
35//! # Feature Flags
36//!
37//! - `object-store`: Enables S3, GCS, Azure, and local filesystem backends.
38//! - `database`: Enables base database connector types.
39//! - `clickhouse`: Enables `ClickHouse` database backend (implies `database`).
40//! - `registry`: Enables the generic registry implementation with stately integration.
41//! - `strum`: Enables `AsRefStr` derives for enum types.
42//!
43//! # Example
44//!
45//! ```rust,ignore
46//! use std::sync::Arc;
47//! use axum::Router;
48//! use stately_arrow::{api, QueryContext, QueryState};
49//!
50//! // Create a registry (implement ConnectorRegistry or use generic::Registry)
51//! let registry: Arc<dyn ConnectorRegistry> = create_registry();
52//!
53//! // Create query context
54//! let query_context = QueryContext::new(registry);
55//!
56//! // Create the router
57//! let arrow_router = api::router(QueryState::new(query_context));
58//!
59//! // Mount under /arrow
60//! let app = Router::new().nest("/arrow", arrow_router);
61//! ```
62
63pub mod api;
64pub mod backend;
65pub mod context;
66#[cfg(feature = "database")]
67pub mod database;
68pub mod error;
69#[cfg(feature = "object-store")]
70pub mod object_store;
71pub mod registry;
72pub mod request;
73pub mod response;
74pub mod state;
75
76// Re-export commonly used types at crate root
77pub use api::openapi::OpenApiDoc;
78pub use backend::{Backend, BackendMetadata, Capability, ConnectionKind, ConnectionMetadata};
79pub use context::{QueryContext, QuerySession, SessionCapability};
80pub use error::{Error, Result};
81pub use registry::ConnectorRegistry;
82#[cfg(feature = "registry")]
83pub use registry::generic;
84pub use request::{
85    ConnectionDetailsRequest, ConnectionSearchQuery, ConnectionSearchTerm, QueryRequest,
86};
87pub use response::{ConnectionDetailsResponse, ListSummary, TableSummary};
88pub use state::QueryState;
stately_arrow/lib.rs

stately_arrow/
lib.rs
