Metadata-Version: 2.4
Name: yami-cli
Version: 0.1.3
Summary: Yet Another Milvus Interface - A command-line tool for Milvus vector database
Project-URL: Homepage, https://github.com/mmga-lab/yami-cli
Project-URL: Repository, https://github.com/mmga-lab/yami-cli
Author: Jeremy Zhu
License-Expression: Apache-2.0
Keywords: cli,command-line,milvus,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.4.3
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: pymilvus>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer[all]>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Yami - Yet Another Milvus Interface

[![PyPI version](https://badge.fury.io/py/yami-cli.svg)](https://pypi.org/project/yami-cli/)
[![Python](https://img.shields.io/pypi/pyversions/yami-cli.svg)](https://pypi.org/project/yami-cli/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A powerful command-line interface for Milvus vector database.

## Installation

```bash
# Install from PyPI
pip install yami-cli

# Or using uv
uv pip install yami-cli
```

### Development Installation

```bash
# Clone and install in development mode
git clone https://github.com/mmga-lab/yami-cli.git
cd yami-cli
uv pip install -e .
```

## Quick Start

```bash
# Test connection
yami connect http://localhost:19530

# List collections
yami --uri http://localhost:19530 collection list

# Create a collection
yami collection create my_collection --dim 768 --metric COSINE

# Insert data
yami data insert my_collection --file data.json

# Search
yami query search my_collection --vector "[0.1, 0.2, ...]" --limit 10

# Query by filter
yami query query my_collection --filter "age > 20"
```

## Configuration

### Connection Profiles

Create connection profiles for easy switching between environments:

```bash
# Add a profile
yami config profile add local --uri http://localhost:19530

# Add a cloud profile
yami config profile add cloud --uri https://xxx.zillizcloud.com --token $TOKEN

# Set default profile
yami config profile use local

# List profiles
yami config profile list
```

### Using Profiles

```bash
# Use default profile
yami collection list

# Use specific profile
yami --profile cloud collection list

# Override with CLI options
yami --uri http://custom:19530 collection list
```

## Commands

### Collection Operations

```bash
yami collection list                    # List all collections
yami collection describe <name>         # Describe a collection
yami collection create <name> --dim N   # Create a collection (quick mode)
yami collection drop <name>             # Drop a collection
yami collection has <name>              # Check if collection exists
yami collection rename <old> <new>      # Rename a collection
yami collection stats <name>            # Get collection statistics
```

#### Create with Field DSL

```bash
# Create with custom fields
yami collection create my_col \
  --field "id:int64:pk:auto" \
  --field "title:varchar:512" \
  --field "embedding:float_vector:768:COSINE"

# Show field DSL syntax
yami collection create --field-help
```

#### Add Field (Milvus 2.6+)

```bash
# Add nullable field
yami collection add-field my_col "score:int64:nullable"

# Add nullable field with default value
yami collection add-field my_col "status:varchar:64:nullable" --default '"active"'

# Add nullable vector field
yami collection add-field my_col "extra_vec:float_vector:128:nullable"
```

### Index Operations

```bash
yami index list <collection>                    # List indexes
yami index describe <collection> <index>        # Describe an index
yami index create <collection> <field>          # Create an index
yami index drop <collection> <index>            # Drop an index
```

### Partition Operations

```bash
yami partition list <collection>        # List partitions
yami partition create <collection> <name>  # Create a partition
yami partition drop <collection> <name>    # Drop a partition
yami partition has <collection> <name>     # Check if partition exists
yami partition stats <collection> <name>   # Get partition statistics
```

### Data Operations

```bash
# Insert from Parquet
yami data insert my_col --sql "SELECT * FROM 'data.parquet'"

# Insert from JSON file
yami data insert my_col --sql "SELECT * FROM read_json('data.json')"

# Insert with transformation
yami data insert my_col --sql "SELECT id, vec FROM 'data.parquet' WHERE score > 0.5"

# Upsert from Parquet
yami data upsert my_col --sql "SELECT * FROM 'updates.parquet'"

# Inline JSON insert
yami data insert my_col --data '[{"id": 1, "vec": [0.1, 0.2, ...]}]'

# Delete by IDs
yami data delete my_col --ids 1,2,3

# Delete by filter
yami data delete my_col --filter "category == 'old'"
```

### Search Operations

#### Vector Search

```bash
# Direct vector input
yami query search my_col --vector "[0.1, 0.2, ...]" --limit 10

# Read vector from Parquet via DuckDB SQL
yami query search my_col --sql "SELECT embedding FROM 'data.parquet' WHERE id=1"

# Batch search from Parquet
yami query search my_col --sql "SELECT embedding FROM 'data.parquet' LIMIT 5"

# Random vector for testing
yami query search my_col --random --limit 10

# With filter and output fields
yami query search my_col --random --filter "category == 'A'" --output-fields "id,title"
```

#### Hybrid Search

Multi-vector search with ranking fusion:

```bash
# Inline JSON requests
yami query hybrid-search my_col \
  --req '{"field": "dense", "vector": [...], "limit": 20}' \
  --req '{"field": "sparse", "vector": {...}, "limit": 20}'

# From Parquet file
yami query hybrid-search my_col --sql "SELECT * FROM 'requests.parquet'"

# From JSON file
yami query hybrid-search my_col --sql "SELECT * FROM read_json('requests.json')"

# With weighted ranker
yami query hybrid-search my_col \
  --sql "SELECT * FROM 'requests.parquet'" \
  --ranker weighted --weights "0.7,0.3"
```

#### Scalar Query

```bash
yami query query <collection> --filter "age > 20"   # Query by filter
yami query query <collection> --ids 1,2,3           # Query by IDs
yami query get <collection> 1,2,3                   # Get by IDs (shorthand)
```

### Import/Export Operations

Export and import data using Parquet format:

```bash
# Export entire collection to directory
yami io export my_col ./export_data

# Export with filter
yami io export my_col ./export_data --filter "category == 'A'"

# Export specific fields
yami io export my_col ./export_data --fields "id,name,embedding"

# Export with custom batch size (rows per file)
yami io export my_col ./export_data --batch-size 50000

# Import from single Parquet file
yami io import my_col data.parquet

# Import from directory (all .parquet files)
yami io import my_col ./export_data/

# Import with SQL transformation
yami io import my_col ./data/ --sql "SELECT id, name, vec FROM data WHERE score > 10"
```

### Database Operations

```bash
yami database list                      # List databases
yami database describe <name>           # Describe a database
yami database create <name>             # Create a database
yami database drop <name>               # Drop a database
yami database use <name>                # Switch database
```

### Load/Release Operations

```bash
yami load collection <name>             # Load collection
yami load partitions <collection> p1,p2 # Load partitions
yami load release <collection>          # Release collection
yami load state <collection>            # Get load state
yami load refresh <collection>          # Refresh load state
```

### Flush Operations

```bash
yami flush collection <name>            # Flush a collection
yami flush all                          # Flush all collections
```

### Compaction Operations

```bash
yami compact run <collection>           # Start compaction
yami compact state <job_id>             # Check compaction state
yami compact wait <job_id>              # Wait for compaction to complete
yami compact list                       # List cached compaction jobs
yami compact clean                      # Clean completed jobs from cache
```

### Segment Operations

```bash
yami segment loaded <collection>        # Show loaded segments
yami segment persistent <collection>    # Show persistent segments
yami segment stats <collection>         # Show segment statistics
```

### Alias Operations

```bash
yami alias list                         # List all aliases
yami alias list <collection>            # List aliases for a collection
yami alias describe <alias>             # Describe an alias
yami alias create <collection> <alias>  # Create an alias
yami alias drop <alias>                 # Drop an alias
yami alias alter <alias> <collection>   # Alter alias to new collection
```

### User/Role Management

```bash
yami user list                          # List users
yami user describe <name>               # Describe a user
yami user create <name> --password      # Create user
yami user drop <name>                   # Drop user
yami user update-password <name>        # Update password
yami user grant-role <user> <role>      # Grant role to user
yami user revoke-role <user> <role>     # Revoke role from user

yami role list                          # List roles
yami role describe <name>               # Describe a role
yami role create <name>                 # Create role
yami role drop <name>                   # Drop role
yami role grant <role> <priv> <obj>     # Grant privilege to role
yami role revoke <role> <priv> <obj>    # Revoke privilege from role
```

### Server Information

```bash
yami server version                     # Get server version
yami server type                        # Get server type (milvus/zilliz)
yami server info                        # Get all server information
```

## Output Formats

```bash
# Table output (default)
yami collection list

# JSON output
yami collection list -o json

# YAML output
yami collection list -o yaml
```

## Shell Completion

```bash
# Install completion for your shell
yami completion install

# Show completion script
yami completion show
```

## Environment Variables

- `MILVUS_URI` - Default Milvus server URI
- `MILVUS_TOKEN` - Default authentication token
- `YAMI_CONFIG_DIR` - Configuration directory (default: `~/.yami`)

## Requirements

- Python 3.10+
- Milvus 2.5+ (some features require 2.6+)

## License

Apache License 2.0
