### Start Wings Development Server (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Starts the Wings platform in development mode. Supports in-memory control plane for local testing and allows configuration of addresses, object storage backends (local, S3-compatible), and data lake formats (Parquet, Delta Lake, Iceberg).

```bash
# Start with default settings (gRPC on 127.0.0.1:7777, HTTP on 127.0.0.1:7780)
wings dev

# Start with custom addresses
wings dev --metadata.address 0.0.0.0:7777 --http.address 0.0.0.0:7780

# Start with local file storage
wings dev --object-store local --object-store.local-path /data/wings

# Start with S3-compatible storage (MinIO)
wings dev --object-store cloud \
  --default.object-store.cloud-bucket my-bucket \
  --default.object-store.cloud-access-key-id minioadmin \
  --default.object-store.cloud-secret-access-key-id minioadmin \
  --default.object-store.cloud-endpoint http://localhost:9000

# Start with Delta Lake format
wings dev --default-data-lake delta
```

--------------------------------

### Rust Client: WingsClient Setup and Push Data

Source: https://context7.com/useairfoil/wings/llms.txt

Connect to a Wings server using the Rust client library and push data. This involves setting up the client, getting a push client for a topic, creating an Arrow RecordBatch, and sending the data.

```rust
use tonic::transport::Channel;
use wings_client::{WingsClient, WriteRequest};
use wings_resources::{TopicName, PartitionValue};
use arrow::array::{StringArray, Int64Array, Float64Array};
use arrow::record_batch::RecordBatch;
use std::sync::Arc;
use std::time::SystemTime;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Wings server
    let channel = Channel::from_static("http://127.0.0.1:7777")
        .connect()
        .await?;

    let client = WingsClient::new(channel);

    // Get a push client for a specific topic
    let topic_name = TopicName::parse("default/default/user_events")?;
    let push_client = client.push_client(topic_name).await?;

    // Create Arrow RecordBatch with data
    let user_ids = StringArray::from(vec!["u123", "u456", "u789"]);
    let event_types = StringArray::from(vec!["click", "view", "click"]);
    let timestamps = Int64Array::from(vec![1705312200000, 1705312201000, 1705312202000]);
    let values = Float64Array::from(vec![1.5, 2.0, 3.5]);

    let schema = push_client.topic_name(); // Schema is inferred from topic
    let batch = RecordBatch::try_from_iter(vec![
        ("user_id", Arc::new(user_ids) as _),
        ("event_type", Arc::new(event_types) as _),
        ("timestamp", Arc::new(timestamps) as _),
        ("value", Arc::new(values) as _),
    ])?;

    // Push data
    let write_request = WriteRequest {
        partition_value: None,
        timestamp: Some(SystemTime::now()),
        data: batch,
    };

    let response = push_client.push(write_request).await?;
    let result = response.wait_for_response().await?;

    match result {
        wings_control_plane_core::log_metadata::CommittedBatch::Accepted(info) => {
            println!("Data accepted: offsets {} to {}", info.start_offset, info.end_offset);
        }
        wings_control_plane_core::log_metadata::CommittedBatch::Rejected(info) => {
            println!("Data rejected: {}", info.reason);
        }
    }

    Ok(())
}

```

--------------------------------

### Interact with Cluster Metadata gRPC API using grpcurl (bash)

Source: https://context7.com/useairfoil/wings/llms.txt

Demonstrates how to use the grpcurl command-line tool to interact with the ClusterMetadataService. Examples include listing tenants, creating a tenant, and creating a topic with a schema.

```bash
# Using grpcurl to interact with the ClusterMetadata API
# List tenants
grpcurl -plaintext 127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/ListTenants

# Create tenant
grpcurl -plaintext -d '{"tenant_id": "my-tenant", "tenant": {}}' \
  127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/CreateTenant

# Create topic with schema
grpcurl -plaintext -d '{
  "parent": "tenants/default/namespaces/default",
  "topic_id": "events",
  "topic": {
    "schema": {
      "fields": [
        {"name": "id", "field_id": 0, "data_type": {"utf8": {}}, "nullable": false},
        {"name": "value", "field_id": 1, "data_type": {"int64": {}}, "nullable": false}
      ]
    }
  }
}' 127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/CreateTopic

```

--------------------------------

### Interact with Log Metadata gRPC API using grpcurl (bash)

Source: https://context7.com/useairfoil/wings/llms.txt

Provides examples of using grpcurl to interact with the LogMetadataService. Demonstrates how to list partitions for a topic and retrieve the log location for reading data.

```bash
# List partitions for a topic
grpcurl -plaintext -d '{
  "topic": "tenants/default/namespaces/default/topics/events"
}' 127.0.0.1:7777 wings.v1.log_metadata.LogMetadataService/ListPartitions

# Get log location for reading
grpcurl -plaintext -d '{
  "topic": "tenants/default/namespaces/default/topics/events",
  "offset": 0,
  "options": {
    "min_rows": 1,
    "max_rows": 1000,
    "deadline": {"seconds": 5}
  }
}' 127.0.0.1:7777 wings.v1.log_metadata.LogMetadataService/GetLogLocation

```

--------------------------------

### Wings CLI SQL Query by Namespace

Source: https://context7.com/useairfoil/wings/llms.txt

Query specific namespaces using the Wings CLI with SQL. This example demonstrates querying the 'orders' table within a specific tenant and namespace.

```bash
wings sql "SELECT * FROM orders WHERE status = 'pending'" \
  tenants/default/namespaces/default \
  --address http://127.0.0.1:7777
```

--------------------------------

### Rust Client: Fetch Data from Topics

Source: https://context7.com/useairfoil/wings/llms.txt

Fetch data from Wings topics using the Rust client library. This example shows how to configure a fetch client with various options like offset, batch size, and timeout, and then enter a loop to fetch data.

```rust
use tonic::transport::Channel;
use wings_client::WingsClient;
use wings_resources::{TopicName, PartitionValue};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let channel = Channel::from_static("http://127.0.0.1:7777")
        .connect()
        .await?;

    let client = WingsClient::new(channel);

    // Create fetch client
    let topic_name = TopicName::parse("default/default/user_events")?;
    let mut fetch_client = client
        .fetch_client(topic_name)
        .await? 
        .with_offset(0)                           // Start from beginning
        .with_min_batch_size(1)                   // Minimum records per batch
        .with_max_batch_size(1000)                // Maximum records per batch
        .with_timeout(Duration::from_millis(250)); // Wait timeout for new data

    // For partitioned topics, specify partition value
    // fetch_client = fetch_client.with_partition(Some(PartitionValue::String("customer_123".to_string())));

    // Fetch loop
    loop {
        let batches = fetch_client.fetch_next().await?;

        if batches.is_empty() {
            println!("No new data, waiting...");
            continue;
        }

        for batch in batches {
            println!("Received {} records", batch.num_rows());
            // Process batch...
        }
    }
}

```

--------------------------------

### Wings CLI Aggregation Queries

Source: https://context7.com/useairfoil/wings/llms.txt

Perform aggregation queries using the Wings CLI. This example calculates the average value and maximum timestamp for different event types from the 'user_events' table.

```bash
wings sql "SELECT event_type, AVG(value) as avg_value, MAX(timestamp) as latest FROM user_events GROUP BY event_type" \
  --address http://127.0.0.1:7777
```

--------------------------------

### Get Topic Details in Wings (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Retrieves detailed information about a specific topic, including basic info or full details with status and conditions. Requires tenant, namespace, topic name, and control plane address. The `--full` flag provides more comprehensive data.

```bash
# Basic info
wings cluster get-topic default/default/user_events --address http://127.0.0.1:7777

# Full details including status and conditions
wings cluster get-topic default/default/user_events --full --address http://127.0.0.1:7777

# Expected output (with --full):
# tenants/default/namespaces/default/topics/user_events
#   fields:
#   - user_id: Utf8
#   - event_type: Utf8
#   status:
#     num partitions: 1
#     conditions:
#     - Type: TableCreated
#       Last Transition Time: 2025-01-15 10:30:00
#       Status: true
#       Reason: Success
#       Message: Table created successfully
```

--------------------------------

### CLI: Get Tables from Wings

Source: https://context7.com/useairfoil/wings/llms.txt

Command-line interface command to retrieve tables from the Wings platform. It requires specifying the namespace and the address of the Wings service.

```bash
wings flight get-tables wings public \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777
```

--------------------------------

### Execute Analytics Queries with Wings CLI Flight SQL (bash)

Source: https://context7.com/useairfoil/wings/llms.txt

Shows how to use the Wings CLI to connect to the Arrow Flight SQL endpoint for executing analytics queries. Includes examples for executing a SELECT statement, retrieving catalogs, and fetching schemas.

```bash
# Using the Wings CLI Flight SQL commands
wings flight execute "SELECT * FROM user_events LIMIT 10" \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777

# Get catalogs
翼 flight get-catalogs \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777

# Get schemas
wings flight get-schemas wings \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777

```

--------------------------------

### Create Namespace in Wings (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Creates a namespace within a tenant to group related topics and define storage configurations. Requires specifying the tenant/namespace, object store, and data lake. Custom flush settings can also be configured.

```bash
# Create namespace with required object store and data lake
wings cluster create-namespace default/events \
  --object-store default/default \
  --data-lake default/default \
  --address http://127.0.0.1:7777

# Create with custom flush settings
wings cluster create-namespace default/logs \
  --object-store default/default \
  --data-lake default/default \
  --flush-millis 5000 \
  --flush-mib 64 \
  --address http://127.0.0.1:7777

# Expected output:
# tenants/default/namespaces/events
#   flush interval: 30s
#   flush size: 32.0 MiB
#   object store: tenants/default/object-stores/default
#   data lake: tenants/default/data-lakes/default
```

--------------------------------

### Create Topic in Wings (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Creates a topic with a defined schema, which stores streams of records with Arrow-compatible schemas. Supports simple and partitioned topics, with a list of supported data types provided. Requires tenant, namespace, topic name, and schema definition.

```bash
# Create a simple topic with string and integer fields
wings cluster create-topic default/default/user_events \
  user_id:string event_type:string timestamp:int64 value:float64 \
  --address http://127.0.0.1:7777

# Create a partitioned topic (partition key must be one of the fields)
wings cluster create-topic default/default/orders \
  order_id:string customer_id:string amount:float64 status:string \
  --partition customer_id \
  --address http://127.0.0.1:7777

# Supported data types: int8, int16, int32, int64, uint8, uint16, uint32, uint64,
# float32, float64, string (utf8), bool (boolean), binary

# Expected output:
# tenants/default/namespaces/default/topics/user_events
#   fields:
#   - user_id: Utf8
#   - event_type: Utf8
#   - timestamp: Int64
#   - value: Float64
```

--------------------------------

### Rust: Execute SQL Query with Arrow Flight SQL Client

Source: https://context7.com/useairfoil/wings/llms.txt

Demonstrates how to use the Arrow Flight SQL client in Rust to connect to a Wings service, set a namespace, execute a SQL query, and fetch results. Requires the `arrow_flight` and `tonic` crates.

```rust
// Using Arrow Flight SQL client in Rust
use arrow_flight::sql::client::FlightSqlServiceClient;
use tonic::transport::Channel;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let channel = Channel::from_static("http://127.0.0.1:7777")
        .connect()
        .await?;

    let mut client = FlightSqlServiceClient::new(channel);

    // Set required namespace header
    client.set_header("x-wings-namespace", "tenants/default/namespaces/default");

    // Execute SQL query
    let flight_info = client
        .execute("SELECT user_id, COUNT(*) as count FROM user_events GROUP BY user_id".to_string(), None)
        .await?;

    // Fetch results from endpoints
    for endpoint in flight_info.endpoint {
        if let Some(ticket) = endpoint.ticket {
            let mut stream = client.do_get(ticket).await?;
            while let Some(batch) = stream.try_next().await? {
                println!("Received batch with {} rows", batch.num_rows());
            }
        }
    }

    Ok(())
}
```

--------------------------------

### List Topics in Wings Namespace (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Lists all topics within a specified namespace in the Wings cluster. Requires the tenant/namespace and control plane address.

```bash
wings cluster list-topics default/default --address http://127.0.0.1:7777

# Expected output:
# tenants/default/namespaces/default/topics/user_events
#   fields:
#   - user_id: Utf8
#   - event_type: Utf8
# tenants/default/namespaces/default/topics/orders
#   partition key: customer_id
#   fields:
#   - order_id: Utf8
#   - customer_id: Utf8
```

--------------------------------

### Rust CancellationToken Cloning for Async Tasks

Source: https://github.com/useairfoil/wings/blob/main/AGENTS.md

Demonstrates how to clone a `CancellationToken` to pass it to a spawned asynchronous task. This allows the spawned task to be cancelled when the original token is cancelled.

```rust
pub async fn do_something(ct: CancellationToken) {
    tokio::spawn({
        let ct = ct.clone();
        async move {
            do_something_else(ct).await;
        }
    })
}
```

--------------------------------

### SQL Queries - CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Execute SQL queries against topics using the Wings CLI, leveraging Apache DataFusion for query execution.

```APIDOC
## POST /sql (CLI)

### Description
Executes SQL queries against data stored in Wings topics using the Apache DataFusion engine via the Wings CLI.

### Method
`POST` (simulated via CLI command)

### Endpoint
`wings sql "<SQL_QUERY>" --address <address>`

### Parameters
#### Path Parameters
- **SQL_QUERY** (string) - Required - The SQL query to execute (e.g., `SELECT * FROM user_events LIMIT 10`).

#### Query Parameters
- **--address** (string) - Required - The address of the Wings cluster (e.g., `http://127.0.0.1:7777`).

### Request Example
```bash
# Simple SELECT query
wings sql "SELECT * FROM user_events LIMIT 10" \
  --address http://127.0.0.1:7777
```

### Response
#### Success Response (200)
- **results** (table) - The results of the SQL query, typically displayed in a tabular format.
```

--------------------------------

### Rust Context Selector for Error Handling

Source: https://github.com/useairfoil/wings/blob/main/AGENTS.md

Shows how to use context selectors with the `context()` method to add descriptive information to errors during fallible operations. This enhances error reporting by providing specific details about the failure.

```rust
use snafu::prelude::*;

fn do_something(input: &str) -> Result<()> {
    do_fallible(input).context(InvalidInputSnafu { field: "input" })?;
    Ok(())
}
```

--------------------------------

### Create Tenant in Wings Cluster (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Creates a new tenant, which serves as the top-level organizational unit in the Wings cluster. Requires specifying the tenant name and the control plane address.

```bash
# Create a tenant named "my-company"
wings cluster create-tenant my-company --address http://127.0.0.1:7777

# Expected output:
# my-company
```

--------------------------------

### Define Log Metadata gRPC Service (protobuf)

Source: https://context7.com/useairfoil/wings/llms.txt

Defines the gRPC service for log metadata operations, including committing data, fetching offsets, and managing partitions. This protobuf definition specifies the RPC methods for interacting with log data.

```protobuf
// Proto definition: wings_control_plane_core/proto/wings/v1/log_metadata.proto

service LogMetadataService {
  // Commit a folio (batch of pages) to storage
  rpc CommitFolio(CommitFolioRequest) returns (CommitFolioResponse);

  // Get log location for reading data
  rpc GetLogLocation(GetLogLocationRequest) returns (GetLogLocationResponse);

  // List partitions for a topic
  rpc ListPartitions(ListPartitionsRequest) returns (ListPartitionsResponse);

  // Request a background task (compaction, table creation)
  rpc RequestTask(RequestTaskRequest) returns (RequestTaskResponse);

  // Complete a background task
  rpc CompleteTask(CompleteTaskRequest) returns (CompleteTaskResponse);
}

```

--------------------------------

### Data Fetching - CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Fetch data from topics using the Wings CLI streaming fetch command. Supports fetching from the beginning, specific offsets, and partitioned topics.

```APIDOC
## GET /fetch (CLI)

### Description
Retrieves data from specified topics using the Wings CLI. Data is streamed continuously by default, with options to specify starting offset, partition, and batching parameters.

### Method
`GET` (simulated via CLI command)

### Endpoint
`wings fetch <namespace>/<topic> [--offset <offset>] [--partition <partition_value>] [--min-batch-size <size>] [--max-batch-size <size>] [--timeout <duration>] --address <address>`

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the topic (e.g., `default/default`).
- **topic** (string) - Required - The name of the topic to fetch data from (e.g., `user_events`).

#### Query Parameters
- **--offset** (integer) - Optional - The offset to start fetching from.
- **--partition** (string) - Optional - The partition value to fetch data from (e.g., `customer_123`).
- **--min-batch-size** (integer) - Optional - Minimum number of records to return in a batch.
- **--max-batch-size** (integer) - Optional - Maximum number of records to return in a batch.
- **--timeout** (string) - Optional - Timeout duration for fetching data (e.g., `500ms`).
- **--address** (string) - Required - The address of the Wings cluster (e.g., `http://127.0.0.1:7777`).

### Request Example
```bash
# Fetch from beginning of topic (streams continuously)
wings fetch default/default/user_events --address http://127.0.0.1:7777

# Fetch from specific offset
wings fetch default/default/user_events --offset 100 --address http://127.0.0.1:7777

# Fetch from partitioned topic
wings fetch default/default/orders --partition customer_123 --address http://127.0.0.1:7777

# Customize batch size and timeout
wings fetch default/default/user_events \
  --min-batch-size 10 \
  --max-batch-size 1000 \
  --timeout 500ms \
  --address http://127.0.0.1:7777
```

### Response
#### Success Response (200)
- **data** (table) - Data fetched from the topic, typically displayed in an Arrow table format.
  - Example:
    ```
    +----------+------------+---------------+-------+
    | user_id  | event_type | timestamp     | value |
    +----------+------------+---------------+-------+
    | u123     | click      | 1705312200000 | 1.5   |
    | u456     | view       | 1705312201000 | 2.0   |
    +----------+------------+---------------+-------+
    ...
    ```
```

--------------------------------

### List Tenants in Wings Cluster (CLI)

Source: https://context7.com/useairfoil/wings/llms.txt

Lists all existing tenants within the Wings cluster. Requires specifying the control plane address.

```bash
wings cluster list-tenants --address http://127.0.0.1:7777

# Expected output:
# default
# my-company
```

--------------------------------

### Define Cluster Metadata gRPC Service (protobuf)

Source: https://context7.com/useairfoil/wings/llms.txt

Defines the gRPC service for managing cluster resources such as tenants, namespaces, topics, object stores, and data lakes. This protobuf definition outlines the available RPC methods and their request/response types.

```protobuf
// Proto definition: wings_control_plane_core/proto/wings/v1/cluster_metadata.proto

service ClusterMetadataService {
  rpc CreateTenant(CreateTenantRequest) returns (Tenant);
  rpc GetTenant(GetTenantRequest) returns (Tenant);
  rpc ListTenants(ListTenantsRequest) returns (ListTenantsResponse);
  rpc DeleteTenant(DeleteTenantRequest) returns (google.protobuf.Empty);

  rpc CreateNamespace(CreateNamespaceRequest) returns (Namespace);
  rpc GetNamespace(GetNamespaceRequest) returns (Namespace);
  rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse);
  rpc DeleteNamespace(DeleteNamespaceRequest) returns (google.protobuf.Empty);

  rpc CreateTopic(CreateTopicRequest) returns (Topic);
  rpc GetTopic(GetTopicRequest) returns (Topic);
  rpc ListTopics(ListTopicsRequest) returns (ListTopicsResponse);
  rpc DeleteTopic(DeleteTopicRequest) returns (google.protobuf.Empty);

  rpc CreateObjectStore(CreateObjectStoreRequest) returns (ObjectStore);
  rpc GetObjectStore(GetObjectStoreRequest) returns (ObjectStore);
  rpc ListObjectStores(ListObjectStoresRequest) returns (ListObjectStoresResponse);
  rpc DeleteObjectStore(DeleteObjectStoreRequest) returns (google.protobuf.Empty);

  rpc CreateDataLake(CreateDataLakeRequest) returns (DataLake);
  rpc GetDataLake(GetDataLakeRequest) returns (DataLake);
  rpc ListDataLakes(ListDataLakesRequest) returns (ListDataLakesResponse);
  rpc DeleteDataLake(DeleteDataLakeRequest) returns (google.protobuf.Empty);
}

```

--------------------------------

### Rust `ensure!` Macro for Validation

Source: https://github.com/useairfoil/wings/blob/main/AGENTS.md

Illustrates the use of the `ensure!` macro for performing validation checks. If the condition is false, it automatically creates and returns a specified error, simplifying validation logic.

```rust
fn validate(value: usize) -> Result<()> {
    ensure!(value > 0, ValueMustBePositiveSnafu);
    Ok(())
}
```

--------------------------------

### Fetch Data from Topic via Wings CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Retrieves data from a specified topic using the Wings CLI streaming fetch command. Supports fetching from the beginning, a specific offset, or a partitioned topic. Options to customize batch size and timeout are available. The `--address` flag specifies the cluster endpoint.

```bash
# Fetch from beginning of topic (streams continuously)
wings fetch default/default/user_events --address http://127.0.0.1:7777

# Fetch from specific offset
wings fetch default/default/user_events --offset 100 --address http://127.0.0.1:7777

# Fetch from partitioned topic
wings fetch default/default/orders --partition customer_123 --address http://127.0.0.1:7777

# Customize batch size and timeout
wings fetch default/default/user_events \
  --min-batch-size 10 \
  --max-batch-size 1000 \
  --timeout 500ms \
  --address http://127.0.0.1:7777
```

--------------------------------

### LogMetadataService API

Source: https://context7.com/useairfoil/wings/llms.txt

gRPC service for log metadata operations, including committing data, fetching offsets, and managing partitions.

```APIDOC
## LogMetadataService API

### Description
Handles log metadata operations such as committing data, retrieving log locations, listing partitions, and managing background tasks.

### Methods
- **CommitFolio**: Commits a batch of pages (folio) to storage.
- **GetLogLocation**: Retrieves the location for reading data from a log.
- **ListPartitions**: Lists the partitions for a given topic.
- **RequestTask**: Requests a background task (e.g., compaction, table creation).
- **CompleteTask**: Completes a background task.

### Example Usage (grpcurl)

**List partitions for a topic:**
```bash
grpcurl -plaintext -d '{
  "topic": "tenants/default/namespaces/default/topics/events"
}' 127.0.0.1:7777 wings.v1.log_metadata.LogMetadataService/ListPartitions
```

**Get log location for reading:**
```bash
grpcurl -plaintext -d '{
  "topic": "tenants/default/namespaces/default/topics/events",
  "offset": 0,
  "options": {
    "min_rows": 1,
    "max_rows": 1000,
    "deadline": {"seconds": 5}
  }
}' 127.0.0.1:7777 wings.v1.log_metadata.LogMetadataService/GetLogLocation
```
```

--------------------------------

### Execute SQL Queries via Wings CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Executes SQL queries against topics using the Apache DataFusion engine via the Wings CLI. The `--address` flag specifies the cluster endpoint. This allows for powerful data analysis directly from the command line.

```bash
# Simple SELECT query
wings sql "SELECT * FROM user_events LIMIT 10" \
  --address http://127.0.0.1:7777
```

--------------------------------

### Data Ingestion - CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Push data into topics using the Wings Command Line Interface (CLI). Supports inline JSON, newline-delimited JSON, data from files, and partitioned topics.

```APIDOC
## POST /push (CLI)

### Description
Ingests data into specified topics using the Wings CLI. Supports various data formats and options for partitioning and explicit timestamps.

### Method
`POST` (simulated via CLI command)

### Endpoint
`wings push <namespace>/<topic> [partition_value] <data> --address <address> [--timestamp <timestamp>]`

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the topic (e.g., `default/default`).
- **topic** (string) - Required - The name of the topic to push data to (e.g., `user_events`).
- **partition_value** (string) - Optional - The value for partitioning if the topic is partitioned (e.g., `customer_123`).

#### Query Parameters
- **data** (string or file path) - Required - The data to push. Can be inline JSON, newline-delimited JSON, or a file path prefixed with `@`.
- **--address** (string) - Required - The address of the Wings cluster (e.g., `http://127.0.0.1:7777`).
- **--timestamp** (string) - Optional - An explicit timestamp for the data in ISO 8601 format (e.g., `2025-01-15T10:30:00Z`).

### Request Example
```bash
# Push inline JSON to a topic
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}' \
  --address http://127.0.0.1:7777

# Push multiple records (newline-delimited JSON)
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}
  {"user_id": "u456", "event_type": "view", "timestamp": 1705312201000, "value": 2.0}' \
  --address http://127.0.0.1:7777

# Push from file
wings push default/default user_events @/path/to/events.json \
  --address http://127.0.0.1:7777

# Push to partitioned topic
wings push default/default orders customer_123 \
  '{"order_id": "o789", "customer_id": "customer_123", "amount": 99.99, "status": "pending"}' \
  --address http://127.0.0.1:7777

# Push with explicit timestamp
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}' \
  --timestamp 2025-01-15T10:30:00Z \
  --address http://127.0.0.1:7777
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating data was pushed (e.g., `Pushed data to topic tenants/default/namespaces/default/topics/user_events`).
- **AcceptedInfo** (object) - Details about the accepted data.
  - **start_offset** (integer) - The starting offset of the accepted data.
  - **end_offset** (integer) - The ending offset of the accepted data.
  - **timestamp** (string) - The timestamp associated with the accepted data.
```

--------------------------------

### Rust Error Delegation Pattern

Source: https://github.com/useairfoil/wings/blob/main/AGENTS.md

Demonstrates how to delegate the `kind()` method to a source error when an error variant wraps another error type. This is useful for propagating error kinds from dependencies or other modules.

```rust
#[snafu(display("Metadata error: {message}"))]
Metadata {
    message: &'static str,
    source: ClusterMetadataError,
}

impl Error {
    pub fn kind(&self) -> ErrorKind {
        match self {
            Self::Metadata { source, .. } => source.kind(),
            // ... other variants
        }
    }
}
```

--------------------------------

### Push Data to Topic via Wings CLI

Source: https://context7.com/useairfoil/wings/llms.txt

Ingests JSON data into a specified topic using the Wings CLI. Supports inline JSON, newline-delimited JSON, data from files, partitioned topics, and explicit timestamps. The `--address` flag specifies the cluster endpoint.

```bash
# Push inline JSON to a topic (namespace is first argument, then topic + data pairs)
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}' \
  --address http://127.0.0.1:7777

# Push multiple records (newline-delimited JSON)
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}
   {"user_id": "u456", "event_type": "view", "timestamp": 1705312201000, "value": 2.0}' \
  --address http://127.0.0.1:7777

# Push from file
wings push default/default user_events @/path/to/events.json \
  --address http://127.0.0.1:7777

# Push to partitioned topic (specify partition value after topic name)
wings push default/default orders customer_123 \
  '{"order_id": "o789", "customer_id": "customer_123", "amount": 99.99, "status": "pending"}' \
  --address http://127.0.0.1:7777

# Push with explicit timestamp
wings push default/default user_events \
  '{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}' \
  --timestamp 2025-01-15T10:30:00Z \
  --address http://127.0.0.1:7777
```

--------------------------------

### Push Data to Topic via HTTP API

Source: https://context7.com/useairfoil/wings/llms.txt

Ingests JSON data into topics using the HTTP ingestion endpoint. Supports pushing single or multiple batches to one or more topics, including partitioned topics and explicit timestamps. The endpoint is typically `http://<address>:7780/v1/push`.

```bash
# Push single batch to a topic
curl -X POST http://127.0.0.1:7780/v1/push \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "tenants/default/namespaces/default",
    "batches": [
      {
        "topic": "user_events",
        "data": [
          {"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5},
          {"user_id": "u456", "event_type": "view", "timestamp": 1705312201000, "value": 2.0}
        ]
      }
    ]
  }'

# Push to multiple topics in one request
curl -X POST http://127.0.0.1:7780/v1/push \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "tenants/default/namespaces/default",
    "batches": [
      {
        "topic": "user_events",
        "data": [{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}]
      },
      {
        "topic": "orders",
        "partition": {"string_value": "customer_123"},
        "data": [{"order_id": "o789", "customer_id": "customer_123", "amount": 99.99, "status": "pending"}]
      }
    ]
  }'

# Push with explicit timestamp (milliseconds since Unix epoch)
curl -X POST http://127.0.0.1:7780/v1/push \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "tenants/default/namespaces/default",
    "batches": [
      {
        "topic": "user_events",
        "timestamp": 1705312200000,
        "data": [{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}]
      }
    ]
  }'
```

--------------------------------

### Arrow Flight SQL Client

Source: https://context7.com/useairfoil/wings/llms.txt

Connect to Wings using Arrow Flight SQL for executing analytics queries and retrieving metadata.

```APIDOC
## Arrow Flight SQL Client

### Description
Interact with Wings for analytics using the Arrow Flight SQL interface via the Wings CLI.

### Commands

- **`wings flight execute "<SQL_QUERY>"`**: Executes an SQL query.
  - `--namespace <namespace>`: Specifies the namespace (e.g., `tenants/default/namespaces/default`).
  - `--address <address>`: The address of the Flight SQL endpoint (e.g., `http://127.0.0.1:7777`).

- **`wings flight get-catalogs`**: Retrieves a list of available catalogs.
  - `--namespace <namespace>`: Specifies the namespace.
  - `--address <address>`: The address of the Flight SQL endpoint.

- **`wings flight get-schemas <catalog>`**: Retrieves a list of schemas within a specified catalog.
  - `--namespace <namespace>`: Specifies the namespace.
  - `--address <address>`: The address of the Flight SQL endpoint.

### Example Usage (Wings CLI)

**Execute SQL query:**
```bash
wings flight execute "SELECT * FROM user_events LIMIT 10" \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777
```

**Get catalogs:**
```bash
wings flight get-catalogs \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777
```

**Get schemas:**
```bash
wings flight get-schemas wings \
  --namespace tenants/default/namespaces/default \
  --address http://127.0.0.1:7777
```
```

--------------------------------

### Wings CLI SQL Query with Filtering

Source: https://context7.com/useairfoil/wings/llms.txt

Execute SQL queries with filtering conditions using the Wings CLI. This command targets a specific SQL query and requires the server address.

```bash
wings sql "SELECT user_id, COUNT(*) as event_count FROM user_events WHERE event_type = 'click' GROUP BY user_id" \
  --address http://127.0.0.1:7777
```

--------------------------------

### ClusterMetadataService API

Source: https://context7.com/useairfoil/wings/llms.txt

gRPC service for managing cluster resources such as tenants, namespaces, topics, object stores, and data lakes.

```APIDOC
## ClusterMetadataService API

### Description
Manages cluster resources including tenants, namespaces, topics, object stores, and data lakes.

### Methods
- **CreateTenant**: Creates a new tenant.
- **GetTenant**: Retrieves information about a specific tenant.
- **ListTenants**: Lists all tenants.
- **DeleteTenant**: Deletes a tenant.
- **CreateNamespace**: Creates a new namespace within a tenant.
- **GetNamespace**: Retrieves information about a specific namespace.
- **ListNamespaces**: Lists all namespaces within a tenant.
- **DeleteNamespace**: Deletes a namespace.
- **CreateTopic**: Creates a new topic within a namespace.
- **GetTopic**: Retrieves information about a specific topic.
- **ListTopics**: Lists all topics within a namespace.
- **DeleteTopic**: Deletes a topic.
- **CreateObjectStore**: Creates a new object store.
- **GetObjectStore**: Retrieves information about a specific object store.
- **ListObjectStores**: Lists all object stores.
- **DeleteObjectStore**: Deletes an object store.
- **CreateDataLake**: Creates a new data lake.
- **GetDataLake**: Retrieves information about a specific data lake.
- **ListDataLakes**: Lists all data lakes.
- **DeleteDataLake**: Deletes a data lake.

### Example Usage (grpcurl)

**List tenants:**
```bash
grpcurl -plaintext 127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/ListTenants
```

**Create tenant:**
```bash
grpcurl -plaintext -d '{"tenant_id": "my-tenant", "tenant": {}}' \
  127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/CreateTenant
```

**Create topic with schema:**
```bash
grpcurl -plaintext -d '{
  "parent": "tenants/default/namespaces/default",
  "topic_id": "events",
  "topic": {
    "schema": {
      "fields": [
        {"name": "id", "field_id": 0, "data_type": {"utf8": {}}, "nullable": false},
        {"name": "value", "field_id": 1, "data_type": {"int64": {}}, "nullable": false}
      ]
    }
  }
}' 127.0.0.1:7777 wings.v1.cluster_metadata.ClusterMetadataService/CreateTopic
```
```

--------------------------------

### Topic Management API

Source: https://context7.com/useairfoil/wings/llms.txt

Manage topics within the Wings cluster. This includes deleting topics, with an option to force deletion including all associated data.

```APIDOC
## DELETE /cluster/delete-topic

### Description
Deletes a topic from the Wings cluster. If the topic contains data, the deletion will fail unless the `--force` flag is used.

### Method
`DELETE` (simulated via CLI command)

### Endpoint
`wings cluster delete-topic <namespace>/<topic> --address <address>`

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace of the topic (e.g., `default/default`).
- **topic** (string) - Required - The name of the topic to delete (e.g., `user_events`).

#### Query Parameters
- **--force** (boolean) - Optional - If set, deletes the topic and all its data, even if it contains data.
- **--address** (string) - Required - The address of the Wings cluster (e.g., `http://127.0.0.1:7777`).

### Request Example
```bash
# Delete topic (fails if topic has data)
wings cluster delete-topic default/default/user_events --address http://127.0.0.1:7777

# Force delete topic including all data
wings cluster delete-topic default/default/user_events --force --address http://127.0.0.1:7777
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the topic was deleted (e.g., `Deleted topic 'default/default/user_events'`).
```

--------------------------------

### Data Ingestion - HTTP API

Source: https://context7.com/useairfoil/wings/llms.txt

Push data into topics using the HTTP API. Allows for batching data and sending to multiple topics in a single request.

```APIDOC
## POST /v1/push

### Description
Ingests data into specified topics via an HTTP POST request. Supports batching multiple records and sending data to different topics or partitions within a single request.

### Method
`POST`

### Endpoint
`http://<host>:<port>/v1/push`

### Parameters
#### Request Body
- **namespace** (string) - Required - The base namespace for the topics (e.g., `tenants/default/namespaces/default`).
- **batches** (array) - Required - An array of batch objects, each specifying data for a topic.
  - **topic** (string) - Required - The name of the topic.
  - **partition** (object) - Optional - Specifies the partition for the data.
    - **string_value** (string) - The string value to use for partitioning.
  - **timestamp** (integer) - Optional - Explicit timestamp in milliseconds since Unix epoch.
  - **data** (array) - Required - An array of data records (JSON objects).

### Request Example
```json
# Push single batch to a topic
{
  "namespace": "tenants/default/namespaces/default",
  "batches": [
    {
      "topic": "user_events",
      "data": [
        {"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5},
        {"user_id": "u456", "event_type": "view", "timestamp": 1705312201000, "value": 2.0}
      ]
    }
  ]
}

# Push to multiple topics in one request
{
  "namespace": "tenants/default/namespaces/default",
  "batches": [
    {
      "topic": "user_events",
      "data": [{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}]
    },
    {
      "topic": "orders",
      "partition": {"string_value": "customer_123"},
      "data": [{"order_id": "o789", "customer_id": "customer_123", "amount": 99.99, "status": "pending"}]
    }
  ]
}

# Push with explicit timestamp (milliseconds since Unix epoch)
{
  "namespace": "tenants/default/namespaces/default",
  "batches": [
    {
      "topic": "user_events",
      "timestamp": 1705312200000,
      "data": [{"user_id": "u123", "event_type": "click", "timestamp": 1705312200000, "value": 1.5}]
    }
  ]
}
```

### Response
#### Success Response (200)
- **batches** (array) - An array of batch results.
  - **_tag** (string) - Status of the batch (`success` or `error`).
  - **start_offset** (integer) - The starting offset of the accepted data (if successful).
  - **end_offset** (integer) - The ending offset of the accepted data (if successful).
  - **message** (string) - Error message (if `_tag` is `error`).

#### Error Response Example
```json
{
  "batches": [
    {"_tag": "error", "message": "failed to parse JSON data for topic user_events: ..."}
  ]
}
```
```

--------------------------------

### Rust Error Type Definition with Snafu

Source: https://github.com/useairfoil/wings/blob/main/AGENTS.md

Defines a custom error enum `Error` using the `snafu` crate, implementing a `kind()` method to map variants to `ErrorKind` enums. It also provides a type alias for `Result` for convenience.

```rust
use snafu::Snafu;
use wings_control_plane::ErrorKind;

#[derive(Debug, Snafu)]
#[snafu(visibility(pub))]
pub enum Error {
    #[snafu(display("Invalid {field}: {reason}"))]
    Validation { field: &'static str, reason: String },

    #[snafu(display("{resource} not found"))]
    NotFound { resource: &'static str },

    #[snafu(display("Internal error: {message}"))]
    Internal { message: String },
}

pub type Result<T, E = Error> = std::result::Result<T, E>;

impl Error {
    pub fn kind(&self) -> ErrorKind {
        match self {
            Self::Validation { .. } => ErrorKind::Validation,
            Self::NotFound { .. } => ErrorKind::NotFound,
            Self::Internal { .. } => ErrorKind::Internal,
        }
    }
}
```