Reference
gRPC services
The gRPC services of the pinned ysearch revision, generated from its .proto files.
ysearch speaks gRPC and RESP only: there is no HTTP API and no SQL. Prometheus metrics and health probes are the only plain-HTTP surface.
The services below are the ones on ysearch main today, package
ysearch.v1: the search engine inherited from yolosearch, and the YS3
prototype's Matching service. Matching is not yet mounted in any server
binary or role (it has no configuration keys): only tests call it over gRPC,
and tools/matchcheck drives the same matcher as a library. See
Matching and dials. The rest of ysearch's client
API (documents, traffic, apps, and the RESP commands) is specified and
arrives from YS5 on; see Status. Protos may change without
compatibility until v1.
Defined in admin_console.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
GetConsoleInfo |
ConsoleInfoRequest |
ConsoleInfo |
|
GetNamespaceStats |
NamespaceStatsRequest |
NamespaceStatsResponse |
|
WatchFleet |
WatchFleetRequest |
stream WatchFleetEvent |
Defined in admin.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
StreamNodeStats |
NodeStatsRequest |
stream NodeStatsFrame |
|
StreamFleetStats |
FleetStatsRequest |
stream FleetStatsFrame |
|
GetIndexDetail |
GetIndexDetailRequest |
IndexDetail |
|
ListSegments |
ListSegmentsRequest |
ListSegmentsResponse |
|
GetCatalogLineage |
GetCatalogLineageRequest |
CatalogLineage |
|
GetEffectiveConfig |
GetEffectiveConfigRequest |
EffectiveConfig |
|
GetFleetTopology |
FleetTopologyRequest |
FleetTopology |
|
GetMetricCatalog |
MetricCatalogRequest |
MetricCatalog |
|
GetOperationalSnapshot |
OperationalSnapshotRequest |
OperationalSnapshot |
|
GetSearchCapabilities |
SearchCapabilitiesRequest |
SearchCapabilities |
|
GetEffectiveConfiguration |
EffectiveConfigurationRequest |
EffectiveConfiguration |
|
GetBuildManifest |
BuildManifestRequest |
BuildManifest |
Defined in catalog.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Resolve |
ResolveCatalogRequest |
CatalogGeneration |
|
AnnounceSegment |
AnnounceSegmentRequest |
AnnounceSegmentResponse |
ConfigService is the per-node configuration surface (MVP spec decisions 3-6). Values are an ephemeral overlay over the file/env/flag layers; a restart drops them. Cluster-wide propagation is a later raft/gossip layer.
Defined in config.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
ListSettings |
ListSettingsRequest |
ListSettingsResponse |
|
GetSetting |
GetSettingRequest |
SettingEntry |
GetSetting returns NOT_FOUND for an unknown key. |
SetSetting |
SetSettingRequest |
SettingEntry |
SetSetting returns NOT_FOUND for an unknown key; FAILED_PRECONDITION for a Startup or CompileTime scoped setting, or for a secret (env-only) setting; INVALID_ARGUMENT for a value that fails the setting's constraint. |
UnsetSetting |
UnsetSettingRequest |
SettingEntry |
UnsetSetting returns NOT_FOUND for an unknown key; FAILED_PRECONDITION for a Startup or CompileTime scoped setting, or for a secret (env-only) setting. Unsetting a key with no runtime override is idempotent: it succeeds and returns the current entry unchanged. |
WatchSettings |
WatchSettingsRequest |
stream WatchSettingsResponse |
WatchSettings sends every matching entry once, then a frame with snapshot_complete = true, then a new entry frame each time a matching setting's VALUE changes (not on provenance-only changes), until the client cancels. |
Defined in index.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
CleanIndex |
IndexLifecycleRequest |
IndexLifecycleResponse |
Clean retains the schema and removes documents; delete removes the index. |
DeleteIndex |
IndexLifecycleRequest |
IndexLifecycleResponse |
|
ProposeSchema |
ProposeSchemaRequest |
ProposeSchemaResponse |
Proposals are offline heuristics and never apply a schema or ingest data. |
GetIndex |
GetIndexRequest |
Index |
|
ValidateQuery |
ValidateQueryRequest |
QueryPlanSummary |
|
ListIndexes |
ListIndexesRequest |
ListIndexesResponse |
ListIndexes names the indexes the object root holds. An index is one with a schema/latest pointer; GetIndex and AdminService.GetIndexDetail describe one. |
ApplySchema |
ApplySchemaRequest |
ApplySchemaResponse |
ApplySchema derives, validates, diffs, and versions a schema. Status codes: unknown index NOT_FOUND; malformed schema or descriptor INVALID_ARGUMENT; non-additive change FAILED_PRECONDITION (message renders the diff); CRD-owned index FAILED_PRECONDITION (M6); lost race beyond retries ABORTED. |
GetIndexSchema |
GetIndexSchemaRequest |
GetIndexSchemaResponse |
GetIndexSchema reads one schema version, latest by default. Unknown index or version is NOT_FOUND. |
Defined in ingest.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Ingest |
stream IngestRequest |
stream IngestAck |
Matching is the matcher's gRPC service (spec/70 §2, spec/60). YS3 implements Article, Pair, CampaignMatches, PutCampaign, GetCampaign, SetCampaignStatus, SetDial, GetDial and Status; the other RPCs of spec/70 §2 (ArticleMatches, Recompile, DryRun, ScorePairs) answer UNIMPLEMENTED. Every request with unknown fields, and every parameter a YS3 node cannot honour, is refused with INVALID_ARGUMENT or FAILED_PRECONDITION and a typed reason, never ignored.
Defined in matching.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Article |
MatchArticleRequest |
MatchArticleResponse |
MATCH.ARTICLE (spec/60 §7.1) with its receipts. |
Pair |
MatchPairRequest |
MatchPairResponse |
MATCH.PAIR: one pair's features and score breakdown, or why it is absent. |
CampaignMatches |
CampaignMatchesRequest |
stream CampaignMatchFrame |
The served set of a campaign under its dial, or every stored row. |
PutCampaign |
MatchCampaign |
MatchCampaign |
CAMPAIGN.PUT: the compile checks run synchronously; a refused campaign is FAILED_PRECONDITION with the typed code. |
GetCampaign |
MatchCampaignRef |
MatchCampaign |
|
SetCampaignStatus |
MatchCampaignStatusRequest |
MatchCampaign |
CAMPAIGN.PAUSE / RESUME / archive. |
SetDial |
MatchDial |
MatchDial |
DIAL.SET: writes the target half of the dial only. |
GetDial |
MatchCampaignRef |
MatchDialStatus |
DIAL.GET: the dial with its effective τ, τ_min and status. |
Status |
MatchingStatusRequest |
MatchingStatus |
Coverage, the checked generation, recomputes. |
ArticleMatches |
MatchArticleRequest |
stream CampaignMatchFrame |
Declared by spec/70 §2; UNIMPLEMENTED in YS3. |
Defined in search.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Search |
SearchRequest |
stream SearchResponse |
SourceService manages the read-only attachments of one process. It is local management, not remote index mutation: a read-only process may change which sources it attaches while remaining unable to write to any of them. Exposure is loopback-only unless an authentication policy is configured, because the entries it accepts name buckets and credential profiles.
Defined in source.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
ListSources |
ListSourcesRequest |
ListSourcesResponse |
|
GetSource |
GetSourceRequest |
GetSourceResponse |
|
PutSource |
PutSourceRequest |
PutSourceResponse |
|
RemoveSource |
RemoveSourceRequest |
RemoveSourceResponse |
|
WatchSources |
WatchSourcesRequest |
stream WatchSourcesResponse |
These run between the roles of one deployment. Clients do not call them.
Defined in internal.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Append |
stream BuildBatch |
stream BuildAck |
|
Seal |
SealRequest |
SealResponse |
|
State |
BuilderStateRequest |
BuilderState |
Defined in internal.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Merge |
MergeRequest |
stream WorkFrame |
Defined in internal.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Advertise |
stream WorkerAdvertisement |
stream PlacementDirective |
|
Lookup |
PlacementLookupRequest |
PlacementSnapshot |
|
Exchange |
stream SoftStateEnvelope |
stream SoftStateEnvelope |
Defined in internal.proto.
| RPC | Request | Response | Notes |
|---|---|---|---|
Execute |
WorkRequest |
stream WorkFrame |
|
CacheState |
CacheStateRequest |
CacheStateResponse |
|
FetchStored |
FetchStoredRequest |
FetchStoredResponse |
FetchStored answers a page's projected documents; no ids is a coverage probe. |