RunCommand Milvus Bridge

Last validated: 2026-05-11

RunCommand is the generic VBase bridge for Milvus unary RPC methods that are not exposed as first-class VBase APIs or CLI commands.

When to Use RunCommand

Use RunCommand when you need:

advanced Milvus methods not mapped in dodil vbase
one-off admin diagnostics on a tenant service
method parity with Milvus without waiting for dedicated CLI coverage

Prefer first-class CLI/API calls for common operations (db, collection, data, index) when available.

RunCommand vs Direct CLI Milvus Endpoint

RunCommand and dodil vbase are not the same execution path.

Aspect	`RunCommand` path	Direct CLI Milvus path
Entry point	`VBaseService/RunCommand` on gateway	Milvus gRPC methods called by CLI (`collection`, `data`, `index`, `status`, `version`)
Endpoint used	`rpc.dev.dodil.io:443` (gRPC) or `https://api.dev.dodil.io:443` (HTTP gateway)	Deployed tenant Milvus endpoint resolved by `dodil vbase db use <service_id>` and stored as `vbase.host:vbase.port`
Request shape	Generic: `service_id` + `method` + JSON `input_payload`	Typed CLI flags mapped to concrete Milvus request protos
Auth/context	Gateway auth with bearer token, plus `dbname`/`db_name` metadata for DB-scoped methods	CLI client sends auth metadata and DB context while dialing tenant endpoint directly
Best for	Methods not exposed by CLI, advanced/rare operations, quick fallback	Day-to-day collection/index/data operations and repeatable scripts
Trade-off	Flexible, but payload authoring and escaping are manual	Easier and safer flag UX, but narrower method coverage

Important clarification:

dodil vbase db ... commands are gateway/service-management commands.
dodil vbase collection|data|index|status|version ... commands target the deployed Milvus endpoint directly after db use sets context.

Decision Rule

If a command exists in dodil vbase collection|data|index|status|version, prefer direct CLI path.
If no CLI command exists for the Milvus operation, use RunCommand through gateway.

Request Contract

`RunVBaseCommandRequest`

Field	Type	Required	Description
`service_id`	`string`	Yes	Tenant service identifier.
`method`	`string`	Yes	Milvus RPC method name, for example `ShowCollections`, `Search`, `CreateIndex`.
`input_payload`	`optional string`	No	JSON string interpreted as request payload for the selected method.

Required metadata

Header	Required	Description
`authorization`	Yes	Bearer token. Request is rejected if missing.
`dbname` or `db_name`	Recommended	DB context for DB-scoped Milvus methods.

Parser and Payload Handling

Most methods deserialize input_payload JSON directly into Milvus request proto types.

Special parser handling exists for:

CreateCollection: supports schema normalization from JSON forms to protobuf bytes.
AddCollectionField: schema field normalization path.
Search: transforms placeholder/vector input into expected protobuf search payload.

Supported Method Families

The executor supports a broad set of unary Milvus methods, including:

Collection lifecycle (CreateCollection, ShowCollections, DescribeCollection, DropCollection, etc.)
Partition lifecycle
Index lifecycle
Data I/O (Insert, Delete, Upsert, Search, HybridSearch, Query, Flush)
Database lifecycle (CreateDatabase, ListDatabases, DescribeDatabase, etc.)
RBAC and credentials
Metrics/health (GetMetrics, CheckHealth, GetVersion)
Resource groups and transfer operations

Known restriction:

Streaming RPC CreateReplicateStream is explicitly unsupported by this generic executor.

Examples

Example 1: ShowCollections (gRPC)


grpcurl -insecure \
  -H "authorization: Bearer $TOKEN" \
  -H "dbname: <db_name>" \
  -d '{
    "service_id":"<service_id>",
    "method":"ShowCollections",
    "input_payload":"{\"db_name\":\"<db_name>\"}"
  }' \
  "rpc.dev.dodil.io:443" dodil.vbase.v1.VBaseService/RunCommand

Example 2: ShowCollections (HTTP)


curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "dbname: <db_name>" \
  -H "Content-Type: application/json" \
  "https://api.dev.dodil.io:443/v1/vbase/<service_id>/run-command" \
  -d '{
    "service_id":"<service_id>",
    "method":"ShowCollections",
    "input_payload":"{\"db_name\":\"<db_name>\"}"
  }'

Example 3: Search (gRPC)


grpcurl -insecure \
  -H "authorization: Bearer $TOKEN" \
  -H "dbname: <db_name>" \
  -d '{
    "service_id":"<service_id>",
    "method":"Search",
    "input_payload":"{\"db_name\":\"<db_name>\",\"collection_name\":\"docs\",\"dsl\":\"\",\"dsl_type\":1,\"output_fields\":[\"id\"],\"partition_names\":[],\"search_params\":[{\"key\":\"anns_field\",\"value\":\"vector\"},{\"key\":\"metric_type\",\"value\":\"L2\"},{\"key\":\"params\",\"value\":\"{}\"},{\"key\":\"topk\",\"value\":\"5\"}],\"nq\":1,\"placeholder_group\":{\"placeholders\":[{\"tag\":\"$0\",\"type\":\"FloatVector\",\"values\":[[0.11,0.12,0.13,0.14,0.15,0.16,0.17,0.18]]}]},\"travel_timestamp\":0,\"guarantee_timestamp\":0,\"not_return_all_meta\":false,\"consistency_level\":0,\"use_default_consistency\":true,\"search_by_primary_keys\":false,\"sub_reqs\":[],\"expr_template_values\":{}}"
  }' \
  "rpc.dev.dodil.io:443" dodil.vbase.v1.VBaseService/RunCommand

Troubleshooting

unauthorized or missing auth errors:
- Ensure authorization: Bearer <token> is present.
method not supported:
- Validate exact Milvus method string.
payload parse failure:
- Confirm input_payload is valid JSON string with escaped quotes.
DB mismatch errors:
- Pass the correct dbname metadata header.