RPC Reference

This page documents Silo’s gRPC API. The protobuf definitions are the source of truth for all RPC interfaces.

Services

Service: Silo

The Silo job queue service.

GetClusterInfo

Get cluster topology for client-side routing. Returns shard ownership information so clients can route requests to the correct node.

rpc GetClusterInfo(GetClusterInfoRequest) returns (GetClusterInfoResponse)

Request: GetClusterInfoRequest

Response: GetClusterInfoResponse

GetNodeInfo

Get information about this node and all the shards it owns.

rpc GetNodeInfo(GetNodeInfoRequest) returns (GetNodeInfoResponse)

Request: GetNodeInfoRequest

Response: GetNodeInfoResponse

Enqueue

Enqueue a new job for processing. The job will be scheduled according to its start_at_ms and processed when limits allow.

rpc Enqueue(EnqueueRequest) returns (EnqueueResponse)

Request: EnqueueRequest

Response: EnqueueResponse

GetJob

Get full details of a job including its current status.

rpc GetJob(GetJobRequest) returns (GetJobResponse)

Request: GetJobRequest

Response: GetJobResponse

GetJobResult

Get the result of a completed job. Returns NOT_FOUND if the job doesn’t exist. Returns FAILED_PRECONDITION if the job hasn’t reached a terminal state.

rpc GetJobResult(GetJobResultRequest) returns (GetJobResultResponse)

Request: GetJobResultRequest

Response: GetJobResultResponse

DeleteJob

Permanently delete a job and all its data. Running jobs should be cancelled first.

rpc DeleteJob(DeleteJobRequest) returns (DeleteJobResponse)

Request: DeleteJobRequest

Response: DeleteJobResponse

CancelJob

Cancel a job. Running jobs will be notified via heartbeat. Jobs in any state can be cancelled.

rpc CancelJob(CancelJobRequest) returns (CancelJobResponse)

Request: CancelJobRequest

Response: CancelJobResponse

RestartJob

Restart a cancelled or failed job for another attempt. Returns FAILED_PRECONDITION if job is not in a restartable state. Returns NOT_FOUND if the job doesn’t exist.

rpc RestartJob(RestartJobRequest) returns (RestartJobResponse)

Request: RestartJobRequest

Response: RestartJobResponse

ExpediteJob

Expedite a future-scheduled job to run immediately. Useful for dragging forward scheduled jobs or skipping retry backoff delays. Returns FAILED_PRECONDITION if job is not in an expeditable state (already running, terminal, cancelled, or task already ready to run). Returns NOT_FOUND if the job doesn’t exist.

rpc ExpediteJob(ExpediteJobRequest) returns (ExpediteJobResponse)

Request: ExpediteJobRequest

Response: ExpediteJobResponse

LeaseTask

Lease a specific job’s task directly, putting it into Running state. Test-oriented helper: workers should use LeaseTasks for normal processing. Returns FAILED_PRECONDITION if the job is running, terminal, or cancelled. Returns NOT_FOUND if the job doesn’t exist.

rpc LeaseTask(LeaseTaskRequest) returns (LeaseTaskResponse)

Request: LeaseTaskRequest

Response: LeaseTaskResponse

LeaseTasks

Lease tasks for a worker to process. Workers should call this periodically to get work. Returns both job tasks and floating limit refresh tasks.

rpc LeaseTasks(LeaseTasksRequest) returns (LeaseTasksResponse)

Request: LeaseTasksRequest

Response: LeaseTasksResponse

ReportOutcome

Report the outcome of a completed job task. Must be called before the task lease expires.

rpc ReportOutcome(ReportOutcomeRequest) returns (ReportOutcomeResponse)

Request: ReportOutcomeRequest

Response: ReportOutcomeResponse

ReportRefreshOutcome

Report the outcome of a floating limit refresh task. Workers compute new max_concurrency and report here.

rpc ReportRefreshOutcome(ReportRefreshOutcomeRequest) returns (ReportRefreshOutcomeResponse)

Request: ReportRefreshOutcomeRequest

Response: ReportRefreshOutcomeResponse

Heartbeat

Extend a task lease and check for cancellation. Workers must heartbeat before lease expires to keep tasks. Returns cancelled=true if the job was cancelled.

rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse)

Request: HeartbeatRequest

Response: HeartbeatResponse

Query

Execute an SQL query against shard data. Returns results as JSON rows.

rpc Query(QueryRequest) returns (QueryResponse)

Request: QueryRequest

Response: QueryResponse

QueryArrow

Execute an SQL query with Arrow IPC streaming response. More efficient for large result sets. First message contains schema, subsequent messages contain record batches.

rpc QueryArrow(QueryArrowRequest) returns (stream ArrowIpcMessage)

Request: QueryArrowRequest

Response: ArrowIpcMessage

CpuProfile

Capture a CPU profile from this node. Returns pprof protobuf data that can be analyzed with pprof or go tool pprof. The profile captures CPU usage for the specified duration.

rpc CpuProfile(CpuProfileRequest) returns (CpuProfileResponse)

Request: CpuProfileRequest

Response: CpuProfileResponse

RequestSplit

Request a shard split operation. Initiates splitting a shard into two child shards at the specified split point. Returns FAILED_PRECONDITION if a split is already in progress. Returns NOT_FOUND if the shard doesn’t exist on this node. Returns INVALID_ARGUMENT if the split point is outside the shard’s range.

rpc RequestSplit(RequestSplitRequest) returns (RequestSplitResponse)

Request: RequestSplitRequest

Response: RequestSplitResponse

GetSplitStatus

Get the status of a shard split operation. Returns the current phase and child shard IDs if a split is in progress. If no split is in progress, returns with in_progress=false.

rpc GetSplitStatus(GetSplitStatusRequest) returns (GetSplitStatusResponse)

Request: GetSplitStatusRequest

Response: GetSplitStatusResponse

ConfigureShard

Configure a shard’s placement ring. Changes which placement ring the shard belongs to, affecting which nodes can own it. The shard will be handed off to a node that participates in the new ring. Returns the previous and current ring assignments.

rpc ConfigureShard(ConfigureShardRequest) returns (ConfigureShardResponse)

Request: ConfigureShardRequest

Response: ConfigureShardResponse

ImportJobs

Import jobs from another system with historical attempts. Unlike Enqueue, ImportJobs accepts completed attempt records and lets Silo take ownership going forward. Used for migrating workloads from other job queues. Each job is imported independently; per-job errors are returned in the response.

rpc ImportJobs(ImportJobsRequest) returns (ImportJobsResponse)

Request: ImportJobsRequest

Response: ImportJobsResponse

ResetShards

Reset all shards owned by this server. WARNING: Destructive operation. Only available in dev mode. Clears all jobs, tasks, queues, and other data.

rpc ResetShards(ResetShardsRequest) returns (ResetShardsResponse)

Request: ResetShardsRequest

Response: ResetShardsResponse

ForceReleaseShard

Force-release a shard lease regardless of the current holder. Operator escape hatch for recovering from permanently lost nodes. After force-release, any live node that desires the shard can acquire it.

rpc ForceReleaseShard(ForceReleaseShardRequest) returns (ForceReleaseShardResponse)

Request: ForceReleaseShardRequest

Response: ForceReleaseShardResponse

Messages

SerializedBytes

Container for arbitrary serialized data with support for multiple encoding formats. Currently only MessagePack is supported, but structured as a union for forward compatibility to add new serialization formats in the future (e.g., JSON, Protobuf). Used for job payloads, results, error data, and query response rows.

Oneof encoding: One of the following:

Field	Type	ID	Description
msgpack	optional bytes	1	Raw MessagePack bytes. Callers should serialize/deserialize using MessagePack.

RetryPolicy

Configuration for automatic job retry on failure. When a job attempt fails, Silo will automatically retry according to this policy.

Field	Type	ID	Description
retry_count	optional uint32	1	Maximum number of retry attempts after the initial attempt fails.
initial_interval_ms	optional int64	2	Initial delay in milliseconds before the first retry.
max_interval_ms	optional int64	3	Maximum delay between retries (caps exponential backoff).
randomize_interval	optional bool	4	If true, adds jitter to retry intervals to prevent thundering herd.
backoff_factor	optional double	5	Multiplier for exponential backoff (e.g., 2.0 doubles delay each retry).

ConcurrencyLimit

Static concurrency limit that restricts how many jobs with the same key can run simultaneously. Jobs sharing the same key will queue up if max_concurrency is reached.

Field	Type	ID	Description
key	optional string	1	Grouping key - jobs with the same key share this limit.
max_concurrency	optional uint32	2	Maximum number of jobs with this key that can run at once.

FloatingConcurrencyLimit

Dynamic concurrency limit where the max_concurrency value is computed by workers. Useful when concurrency should be based on external factors like API rate limits. Workers periodically receive refresh tasks to update the limit.

Field	Type	ID	Description
key	optional string	1	Grouping key - jobs with the same key share this limit.
default_max_concurrency	optional uint32	2	Initial max concurrency used until first worker refresh.
refresh_interval_ms	optional int64	3	How often workers receive refresh tasks (milliseconds).
metadata	optional map<string, string>	4	Arbitrary data passed to workers during refresh (e.g., API credentials).

RateLimitRetryPolicy

Retry policy for when a job is blocked by a rate limit. Configures how long workers should wait before retrying the rate limit check.

Field	Type	ID	Description
initial_backoff_ms	optional int64	1	Initial wait time in milliseconds when rate limited.
max_backoff_ms	optional int64	2	Maximum wait time between retries.
backoff_multiplier	optional double	3	Multiplier for exponential backoff (default 2.0).
max_retries	optional uint32	4	Max retries before failing the job (0 = infinite until reset_time).

GubernatorRateLimit

Rate limit backed by the Gubernator distributed rate limiting service. Allows controlling job throughput based on request rates.

Field	Type	ID	Description
name	optional string	1	Human-readable name for debugging and metrics.
unique_key	optional string	2	Unique identifier for this rate limit instance (e.g., user ID).
limit	optional int64	3	Maximum number of requests allowed within the duration.
duration_ms	optional int64	4	Time window in milliseconds for the rate limit.
hits	optional int32	5	Number of hits this job consumes (usually 1).
algorithm	optional GubernatorAlgorithm	6	Algorithm for rate limiting (token bucket or leaky bucket).
behavior	optional int32	7	Behavior flags - combine GubernatorBehavior values with OR.
retry_policy	optional RateLimitRetryPolicy	8	Policy for retrying when rate limited.

Limit

Union type representing any kind of limit that can be applied to a job. Jobs can have multiple limits; all must be satisfied before execution.

Oneof limit: One of the following:

Field	Type	ID	Description
concurrency	optional ConcurrencyLimit	1	Static concurrency limit.
rate_limit	optional GubernatorRateLimit	2	Gubernator-based rate limit.
floating_concurrency	optional FloatingConcurrencyLimit	3	Dynamic worker-computed concurrency limit.

EnqueueRequest

Request to enqueue a new job for processing.

Oneof _retry_policy: One of the following:

Field	Type	ID	Description
retry_policy	optional RetryPolicy	5	Retry configuration. If absent, job fails on first error.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	8	Tenant ID for multi-tenant deployments. Optional.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job should be stored.
id	optional string	2	Optional job ID. If empty, a random UUID is generated.
priority	optional uint32	3	Priority from 0-99. Lower is higher priority (0 = highest).
start_at_ms	optional int64	4	Unix timestamp (ms) for future scheduling. 0 = run immediately.
payload	optional SerializedBytes	6	Opaque serialized payload passed to workers.
limits	repeated Limit	7	Ordered list of limits checked before execution.
metadata	optional map<string, string>	9	Arbitrary key/value metadata stored with the job.
task_group	optional string	10	Task group for organizing tasks. Required. Tasks are enqueued into this group.

EnqueueResponse

Response after successfully enqueueing a job.

Field	Type	ID	Description
id	optional string	1	The job’s ID (either provided or auto-generated).

GetJobRequest

Request to retrieve details about a specific job.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job is stored.
id	optional string	2	The job’s unique ID.
include_attempts	optional bool	4	If true, include all attempts in the response. Defaults to false.

JobAttempt

A single execution attempt of a job.

Oneof _finished_at_ms: One of the following:

Field	Type	ID	Description
finished_at_ms	optional int64	6	Unix timestamp (ms) when attempt finished. Present if completed.

Oneof _result: One of the following:

Field	Type	ID	Description
result	optional SerializedBytes	7	Result data if attempt succeeded.

Oneof _error_code: One of the following:

Field	Type	ID	Description
error_code	optional string	8	Error code if attempt failed.

Oneof _error_data: One of the following:

Field	Type	ID	Description
error_data	optional SerializedBytes	9	Error details if attempt failed.

Fields:

Field	Type	ID	Description
job_id	optional string	1	The job’s unique ID.
attempt_number	optional uint32	2	Which attempt this is (1 = first attempt).
task_id	optional string	3	Unique task ID for this attempt.
status	optional AttemptStatus	4	Current status of the attempt.
started_at_ms	optional int64	5	Unix timestamp (ms) when attempt started. Present for all attempts.

GetJobResponse

Full details of a job including its current state.

Oneof _retry_policy: One of the following:

Field	Type	ID	Description
retry_policy	optional RetryPolicy	5	Retry policy if configured.

Oneof _next_attempt_starts_after_ms: One of the following:

Field	Type	ID	Description
next_attempt_starts_after_ms	optional int64	11	Unix timestamp (ms) when the next attempt will start. Present for scheduled jobs, absent for running or terminal jobs.

Oneof _result: One of the following:

Field	Type	ID	Description
result	optional SerializedBytes	13	Result data from the last attempt, if the job succeeded.

Fields:

Field	Type	ID	Description
id	optional string	1	The job’s unique ID.
priority	optional uint32	2	Job priority (0 = highest, 99 = lowest).
enqueue_time_ms	optional int64	3	Unix timestamp (ms) when job was enqueued.
payload	optional SerializedBytes	4	The job’s payload data.
limits	repeated Limit	6	Limits declared on this job.
metadata	optional map<string, string>	7	Metadata key/value pairs.
status	optional JobStatus	8	Current job status.
status_changed_at_ms	optional int64	9	Unix timestamp (ms) of last status change.
attempts	repeated JobAttempt	10	All attempts for this job. Only populated if include_attempts was true in the request.
task_group	optional string	12	Task group this job’s tasks are enqueued into.

GetJobResultRequest

Request to get the result of a completed job. Only succeeds if the job has reached a terminal state (succeeded, failed, or cancelled).

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job is stored.
id	optional string	2	The job’s unique ID.

GetJobResultResponse

Result of a completed job. Check status to determine which result field is populated.

Oneof result: The result depends on the terminal status.

Field	Type	ID	Description
success_data	optional SerializedBytes	4	Present if status == SUCCEEDED. Contains job result.
failure	optional JobFailure	5	Present if status == FAILED. Contains error details.
cancelled	optional JobCancelled	6	Present if status == CANCELLED. Contains cancellation info.

Fields:

Field	Type	ID	Description
id	optional string	1	The job’s unique ID.
status	optional JobStatus	2	Terminal status: SUCCEEDED, FAILED, or CANCELLED.
finished_at_ms	optional int64	3	Unix timestamp (ms) when job reached terminal state.

JobFailure

Error information for a failed job.

Field	Type	ID	Description
error_code	optional string	1	Application-defined error code.
error_data	optional SerializedBytes	2	Serialized error details.

JobCancelled

Information about a cancelled job.

Field	Type	ID	Description
cancelled_at_ms	optional int64	1	Unix timestamp (ms) when cancellation was requested.

DeleteJobRequest

Request to permanently delete a job and all its data.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job is stored.
id	optional string	2	The job’s unique ID.

DeleteJobResponse

Response confirming job deletion.

No fields

CancelJobRequest

Request to cancel a job. Running jobs will be notified via heartbeat response.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job is stored.
id	optional string	2	The job’s unique ID.

CancelJobResponse

Response confirming cancellation was requested.

No fields

RestartJobRequest

Restart a cancelled or failed job, allowing it to be processed again. The job will get a fresh set of retries according to its retry policy.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3

Fields:

Field	Type	ID	Description
shard	optional string	1
id	optional string	2

RestartJobResponse

No fields

ExpediteJobRequest

Expedite a future-scheduled job to run immediately. This is useful for dragging forward a job that was scheduled for the future, or for skipping retry backoff delays on a mid-retry job.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3

Fields:

Field	Type	ID	Description
shard	optional string	1
id	optional string	2

ExpediteJobResponse

No fields

LeaseTaskRequest

Lease a specific job’s task directly, putting it into Running state. This is a test-oriented helper: workers should use LeaseTasks for normal processing. Bypasses concurrency/rate-limit processing and creates a RunAttempt lease directly. Returns FAILED_PRECONDITION if the job is running, terminal, or cancelled. Returns NOT_FOUND if the job doesn’t exist.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job is stored.
id	optional string	2	The job’s unique ID.
worker_id	optional string	4	Worker ID to assign the lease to.

LeaseTaskResponse

Field	Type	ID	Description
task	optional Task	1	The leased task.

LeaseTasksRequest

Lease tasks for processing from this server. By default, leases from all shards this server owns (fair distribution). If shard is specified, filters to only that shard.

Oneof _shard: One of the following:

Field	Type	ID	Description
shard	optional string	1	optional filter - if set, only lease from this shard (UUID)

Fields:

Field	Type	ID	Description
worker_id	optional string	2
max_tasks	optional uint32	3
task_group	optional string	4	Required. Task group to poll tasks from.

Task

A task representing a single job attempt leased to a worker.

Oneof _tenant_id: One of the following:

Field	Type	ID	Description
tenant_id	optional string	3	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
id	optional string	1	Unique task ID (different from job ID).
job_id	optional string	2	ID of the job this task belongs to.
attempt_number	optional uint32	4	Which attempt this is (1 = first attempt). Monotonically increasing across restarts.
relative_attempt_number	optional uint32	5	Attempt within current run (1 = first attempt since last restart). Resets on restart.
is_last_attempt	optional bool	6	True if this is the final attempt (no more retries after this run).
metadata	optional map<string, string>	7	Metadata key/value pairs from the job.
limits	repeated Limit	8	Limits declared on this job (concurrency, rate, floating).
payload	optional SerializedBytes	9	The job’s payload for the worker to process.
priority	optional uint32	10	Job priority (for informational purposes).
shard	optional string	11	Shard ID (UUID) this task came from (needed for reporting outcome).
task_group	optional string	12	Task group this task belongs to.
lease_ms	optional int64	13	How long the lease lasts. Heartbeat before this expires.

RefreshFloatingLimitTask

Task for refreshing a floating concurrency limit. Workers compute the new max_concurrency and report back.

Oneof _tenant_id: One of the following:

Field	Type	ID	Description
tenant_id	optional string	9	Tenant ID if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
id	optional string	1	Unique task ID for this refresh.
queue_key	optional string	2	The floating limit key being refreshed.
current_max_concurrency	optional uint32	3	Current max concurrency value.
last_refreshed_at_ms	optional int64	4	Unix timestamp (ms) of last refresh.
metadata	optional map<string, string>	5	Metadata from the limit definition.
lease_ms	optional int64	6	How long the lease lasts. Heartbeat before this expires.
shard	optional string	7	Shard ID (UUID) this task came from (needed for reporting outcome).
task_group	optional string	8	Task group this refresh task belongs to.

LeaseTasksResponse

Response containing tasks leased to a worker.

Field	Type	ID	Description
tasks	repeated Task	1	Job execution tasks.
refresh_tasks	repeated RefreshFloatingLimitTask	2	Floating limit refresh tasks.

ReportOutcomeRequest

Request to report the outcome of a completed task. Note: tenant is determined from the task lease, not from the request.

Oneof outcome: One of the following:

Field	Type	ID	Description
success	optional SerializedBytes	3	Job succeeded. Contains result data from executing the job.
failure	optional Failure	4	Job failed. Contains error details.
cancelled	optional Cancelled	6	Worker acknowledges job was cancelled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) the task came from.
task_id	optional string	2	The task’s unique ID.

Failure

Error details for a failed task.

Field	Type	ID	Description
code	optional string	1	Application-defined error code.
data	optional SerializedBytes	2	Serialized error details.

Cancelled

Marker indicating the worker acknowledges the job was cancelled.

No fields

ReportOutcomeResponse

Response confirming outcome was recorded.

No fields

ReportRefreshOutcomeRequest

Request to report the outcome of a floating limit refresh task. Note: tenant is determined from the task lease, not from the request.

Oneof outcome: One of the following:

Field	Type	ID	Description
success	optional RefreshSuccess	4	Refresh succeeded with new max concurrency.
failure	optional RefreshFailure	5	Refresh failed.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) the task came from.
task_id	optional string	2	The task’s unique ID.

RefreshSuccess

Successful floating limit refresh with the new computed value.

Field	Type	ID	Description
new_max_concurrency	optional uint32	1	New max concurrency computed by the worker.

RefreshFailure

Error during floating limit refresh.

Field	Type	ID	Description
code	optional string	1	Error code.
message	optional string	2	Human-readable error message.

ReportRefreshOutcomeResponse

Response confirming refresh outcome was recorded.

No fields

HeartbeatRequest

Request to extend a task lease and check for cancellation. Workers must heartbeat before lease_ms expires to keep the task. Note: tenant is determined from the task lease, not from the request.

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) the task came from.
worker_id	optional string	2	Worker ID that holds the lease.
task_id	optional string	3	The task’s unique ID.

HeartbeatResponse

Response indicating if the lease was extended and if the job was cancelled.

Oneof _cancelled_at_ms: One of the following:

Field	Type	ID	Description
cancelled_at_ms	optional int64	2	Unix timestamp (ms) when cancellation was requested, if cancelled.

Fields:

Field	Type	ID	Description
cancelled	optional bool	1	True if job was cancelled. Worker should stop and report Cancelled.

QueryNull

No fields

QueryParameter

A single bind parameter value for SQL query placeholders.

Oneof value: One of the following:

Field	Type	ID	Description
bool_value	optional bool	1
int64_value	optional int64	2
uint64_value	optional uint64	3
float64_value	optional double	4
string_value	optional string	5
bytes_value	optional bytes	6
null_value	optional QueryNull	7

QueryRequest

Request to execute an arbitrary SQL query against shard data. Useful for ad-hoc inspection and debugging.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID to scope results, if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) to query.
sql	optional string	2	SQL query string.
parameters	repeated QueryParameter	4	Optional SQL bind parameters ($1, $2, …).

ColumnInfo

Metadata about a column in query results.

Field	Type	ID	Description
name	optional string	1	Column name.
data_type	optional string	2	Arrow/DataFusion type as string (e.g., “Utf8”, “Int64”).

QueryResponse

Query results with rows as serialized objects.

Field	Type	ID	Description
columns	repeated ColumnInfo	1	Schema information for the result columns.
rows	repeated SerializedBytes	2	Each row as a serialized object.
row_count	optional int32	3	Total number of rows returned.

QueryArrowRequest

Request to execute SQL query with Arrow IPC streaming response. More efficient than QueryResponse for large result sets.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	3	Tenant ID to scope results, if multi-tenancy is enabled.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) to query.
sql	optional string	2	SQL query string.
parameters	repeated QueryParameter	4	Optional SQL bind parameters ($1, $2, …).

ArrowIpcMessage

Arrow IPC encoded message. Part of a streaming response.

Field	Type	ID	Description
ipc_data	optional bytes	1	Arrow IPC stream data. First message is schema, subsequent are record batches.

GetClusterInfoRequest

Request to get cluster topology for client-side routing.

No fields

ShardOwner

Information about which node owns a specific shard.

Oneof _placement_ring: One of the following:

Field	Type	ID	Description
placement_ring	optional string	6	Placement ring this shard belongs to (empty = default ring).

Fields:

Field	Type	ID	Description
shard_id	optional string	1	The shard ID (UUID).
grpc_addr	optional string	2	gRPC address of the node owning this shard.
node_id	optional string	3	Unique identifier of the owning node.
range_start	optional string	4	Inclusive start of the tenant_id range owned by this shard.
range_end	optional string	5	Exclusive end of the tenant_id range owned by this shard.

ClusterMember

Information about a cluster member node.

Field	Type	ID	Description
node_id	optional string	1	Unique identifier of this node.
grpc_addr	optional string	2	gRPC address of this node.
placement_rings	repeated string	3	Placement rings this node participates in.

GetClusterInfoResponse

Cluster topology information.

Field	Type	ID	Description
num_shards	optional uint32	1	Total number of shards in the cluster.
shard_owners	repeated ShardOwner	2	Mapping of each shard to its owner.
this_node_id	optional string	3	Node ID of the server responding.
this_grpc_addr	optional string	4	gRPC address of the server responding.
members	repeated ClusterMember	5	All cluster members with their ring participation.

ResetShardsRequest

Request to reset all shards owned by this server. WARNING: Destructive operation. Only available in dev mode.

No fields

ResetShardsResponse

Response confirming shards were reset.

Field	Type	ID	Description
shards_reset	optional uint32	1	Number of shards that were cleared.

CpuProfileRequest

Request to capture a CPU profile from this node. Used for production debugging and performance analysis.

Field	Type	ID	Description
duration_seconds	optional uint32	1	How long to profile (1-300 seconds). Default 30.
frequency	optional uint32	2	Sampling frequency in Hz (1-1000). Default 100.

CpuProfileResponse

CPU profile data in pprof protobuf format. Can be analyzed with pprof or go tool pprof.

Field	Type	ID	Description
profile_data	optional bytes	1	pprof protobuf bytes (not gzip compressed).
duration_seconds	optional uint32	2	Actual duration profiled.
samples	optional uint64	3	Number of samples collected.

RequestSplitRequest

Request to initiate a shard split operation.

Field	Type	ID	Description
shard_id	optional string	1	Shard ID (UUID) of the shard to split.
split_point	optional string	2	Tenant ID where to split the keyspace.

RequestSplitResponse

Response after initiating a shard split.

Field	Type	ID	Description
left_child_id	optional string	1	UUID of the left child shard [parent_start, split_point).
right_child_id	optional string	2	UUID of the right child shard [split_point, parent_end).
phase	optional string	3	Current split phase (e.g., “SplitRequested”).

GetSplitStatusRequest

Request to get the status of a shard split operation.

Field	Type	ID	Description
shard_id	optional string	1	Parent shard ID (UUID) of the split operation.

GetSplitStatusResponse

Response with the current split status. Returns empty if no split is in progress for the shard.

Field	Type	ID	Description
in_progress	optional bool	1	True if a split is in progress for this shard.
phase	optional string	2	Current split phase (empty if not in progress).
left_child_id	optional string	3	UUID of the left child shard (empty if not in progress).
right_child_id	optional string	4	UUID of the right child shard (empty if not in progress).
split_point	optional string	5	Tenant ID at which the split occurs (empty if not in progress).
initiator_node_id	optional string	6	Node ID that initiated the split.
requested_at_ms	optional int64	7	Unix timestamp (ms) when split was requested.

OwnedShardInfo

Information about a shard owned by a node, including counters and cleanup status.

Field	Type	ID	Description
shard_id	optional string	1	The shard ID (UUID).
total_jobs	optional int64	2	Total number of jobs in the shard (not deleted).
completed_jobs	optional int64	3	Number of jobs in terminal states (Succeeded, Failed, Cancelled).
cleanup_status	optional string	4	Cleanup status: “CompactionDone”, “CleanupPending”, “CleanupRunning”, “CleanupDone”.
created_at_ms	optional int64	5	Unix timestamp (ms) when this shard was first created/initialized.
cleanup_completed_at_ms	optional int64	6	Unix timestamp (ms) when cleanup completed (0 if not applicable or not completed).

GetNodeInfoRequest

Request to get node information including owned shards with their counters and cleanup status.

No fields

GetNodeInfoResponse

Response with node information and details for all shards owned by this node.

Field	Type	ID	Description
node_id	optional string	1	Unique identifier of this node.
owned_shards	repeated OwnedShardInfo	2	Information for each shard owned by this node.
placement_rings	repeated string	3	Placement rings this node participates in.

ConfigureShardRequest

Request to configure a shard’s placement ring.

Oneof _placement_ring: One of the following:

Field	Type	ID	Description
placement_ring	optional string	2	The placement ring to assign (empty/null = default ring).

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	100	Optional tenant ID (for multi-tenant mode).

Fields:

Field	Type	ID	Description
shard	optional string	1	The shard ID (UUID) to configure.

ConfigureShardResponse

Response after configuring a shard’s placement ring.

Field	Type	ID	Description
previous_ring	optional string	1	The placement ring before the change (empty = default ring).
current_ring	optional string	2	The placement ring after the change (empty = default ring).

ImportAttempt

A historical attempt record for job import. All attempts must be in terminal states (no Running).

Oneof _result: One of the following:

Field	Type	ID	Description
result	optional SerializedBytes	4	Present if succeeded.

Oneof _error_code: One of the following:

Field	Type	ID	Description
error_code	optional string	5	Present if failed.

Oneof _error_data: One of the following:

Field	Type	ID	Description
error_data	optional SerializedBytes	6	Present if failed.

Fields:

Field	Type	ID	Description
status	optional AttemptStatus	1	Must be terminal (SUCCEEDED, FAILED, or CANCELLED).
started_at_ms	optional int64	2	When the attempt started (epoch ms).
finished_at_ms	optional int64	3	When the attempt finished (epoch ms).

ImportJobRequest

Request to import a single job from another system. Unlike Enqueue, ImportJob accepts historical attempts and lets Silo take ownership going forward.

Oneof _retry_policy: One of the following:

Field	Type	ID	Description
retry_policy	optional RetryPolicy	6	Retry configuration.

Oneof _tenant: One of the following:

Field	Type	ID	Description
tenant	optional string	9	Tenant ID for multi-tenant deployments.

Fields:

Field	Type	ID	Description
shard	optional string	1	Shard ID (UUID) where the job should be stored.
id	optional string	2	Required job ID (migration preserves IDs).
priority	optional uint32	3	Priority from 0-99. Lower is higher priority.
enqueue_time_ms	optional int64	4	Original enqueue time from source system (0 = now).
start_at_ms	optional int64	5	When the next attempt should start (0 = now, only for non-terminal).
payload	optional SerializedBytes	7	Opaque serialized payload.
limits	repeated Limit	8	Ordered list of limits.
metadata	optional map<string, string>	10	Arbitrary key/value metadata.
task_group	optional string	11	Task group for organizing tasks.
attempts	repeated ImportAttempt	12	Historical attempts, all terminal.

ImportJobsRequest

Batch request to import multiple jobs.

Field	Type	ID	Description
jobs	repeated ImportJobRequest	1

ImportJobResult

Result of importing a single job.

Oneof _error: One of the following:

Field	Type	ID	Description
error	optional string	3	Error message if import failed.

Fields:

Field	Type	ID	Description
id	optional string	1	The job’s ID.
success	optional bool	2	Whether the import succeeded.
status	optional JobStatus	4	The determined status of the imported job.

ImportJobsResponse

Response containing results for each imported job.

Field	Type	ID	Description
results	repeated ImportJobResult	1

ForceReleaseShardRequest

Request to force-release a shard’s ownership lease. Operator escape hatch for permanently lost nodes.

Field	Type	ID	Description
shard	optional string	1	The shard ID (UUID) to force-release.

ForceReleaseShardResponse

Response after force-releasing a shard lease.

Field	Type	ID	Description
released	optional bool	1	True if the lease was released.

Enums

GubernatorAlgorithm

Rate limiting algorithm for Gubernator-based limits.

Value	Number	Description
GUBERNATOR_ALGORITHM_TOKEN_BUCKET	0	Token bucket: tokens refill at steady rate, requests consume tokens.
GUBERNATOR_ALGORITHM_LEAKY_BUCKET	1	Leaky bucket: requests processed at fixed rate, excess queued.

GubernatorBehavior

Behavior flags for Gubernator rate limits. Can be combined via bitwise OR.

Value	Number	Description
GUBERNATOR_BEHAVIOR_BATCHING	0	Default: batch rate limit checks to peers for efficiency.
GUBERNATOR_BEHAVIOR_NO_BATCHING	1	Send each rate limit check immediately (lower latency, higher load).
GUBERNATOR_BEHAVIOR_GLOBAL	2	Synchronize rate limit globally across all Gubernator peers.
GUBERNATOR_BEHAVIOR_DURATION_IS_GREGORIAN	4	Reset duration on calendar boundaries (minute, hour, day).
GUBERNATOR_BEHAVIOR_RESET_REMAINING	8	Force reset the remaining counter on this request.
GUBERNATOR_BEHAVIOR_DRAIN_OVER_LIMIT	16	Set remaining to zero on first over-limit event.

JobStatus

Current state of a job in its lifecycle.

Value	Number	Description
JOB_STATUS_SCHEDULED	0	Job is waiting to be executed (queued or scheduled for future).
JOB_STATUS_RUNNING	1	Job is currently being processed by a worker.
JOB_STATUS_SUCCEEDED	2	Job completed successfully.
JOB_STATUS_FAILED	3	Job failed after exhausting all retry attempts.
JOB_STATUS_CANCELLED	4	Job was cancelled before completion.

AttemptStatus

Status of a job attempt in its lifecycle.

Value	Number	Description
ATTEMPT_STATUS_RUNNING	0	Attempt is currently running.
ATTEMPT_STATUS_SUCCEEDED	1	Attempt completed successfully.
ATTEMPT_STATUS_FAILED	2	Attempt failed.
ATTEMPT_STATUS_CANCELLED	3	Attempt was cancelled.