Class IndexAdminResource

java.lang.Object

ai.pipestream.module.pipelineprobe.IndexAdminResource

@Path("/test-sidecar/v1/indices")
@Produces("application/json")
@Consumes("application/json")
public class IndexAdminResource
extends Object

OpenSearch index administration REST API for the Quinoa UI. Backed by opensearch-manager gRPC, not HTTP proxy.

Blocking gRPC stub on virtual threads — no Mutiny.

Constructor Summary

Constructors

Constructor	Description
IndexAdminResource()	Creates the index administration resource.

Method Summary

Modifier and Type	Method	Description
jakarta.ws.rs.core.Response	createIndex(Map<String,Object> payload)	Creates a kNN vector index.
jakarta.ws.rs.core.Response	deleteIndex(String indexName, boolean force)	Deletes a single index.
jakarta.ws.rs.core.Response	deprovisionIndex(Map<String,Object> payload)	Tears down a previously-provisioned index set: deletes the parent index plus every index whose name starts with indexName + "--" (the OSM convention for --chunk--… and --vs--… side indices).
jakarta.ws.rs.core.Response	getDocument(String indexName, String documentId)	Fetches a single stored document by index and document id.
jakarta.ws.rs.core.Response	getIndexMapping(String indexName)	Returns the field mapping of the named index as JSON.
jakarta.ws.rs.core.Response	getIndexStats(String indexName)	Returns document-count and size statistics for a single index.
jakarta.ws.rs.core.Response	indexExists(String indexName)	Reports whether the named index exists.
jakarta.ws.rs.core.Response	listIndices(String prefix)	Lists OpenSearch indices, optionally filtered by name prefix.
jakarta.ws.rs.core.Response	provisionIndex(Map<String,Object> payload)	Pre-provisions a fresh parent index plus every --chunk-- / --vs-- side index required by the supplied SemanticConfigs, and populates the vector_set_index_binding cache.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

IndexAdminResource

public IndexAdminResource()

Creates the index administration resource. Instances are managed by the JAX-RS runtime.

Method Details

listIndices

@GET
public jakarta.ws.rs.core.Response listIndices(@QueryParam("prefix")
 String prefix)

Lists OpenSearch indices, optionally filtered by name prefix.

Each returned entry carries the index name, document count, size in bytes, status, and (when present) a list of its vector-field summaries.

Parameters:

prefix - optional prefix filter; when null or blank, all indices are listed

Returns:

a 200 JSON response with indices and count, or an error response

getIndexStats

@GET
@Path("/{indexName}/stats")
public jakarta.ws.rs.core.Response getIndexStats(@PathParam("indexName")
 String indexName)

Returns document-count and size statistics for a single index.

Parameters:

indexName - the index to inspect

Returns:

a 200 JSON response with success, documentCount, sizeInBytes, and message, or an error response

indexExists

@GET
@Path("/{indexName}/exists")
public jakarta.ws.rs.core.Response indexExists(@PathParam("indexName")
 String indexName)

Reports whether the named index exists.

Parameters:

indexName - the index to check

Returns:

a 200 JSON response with indexName and exists, or an error response

getIndexMapping

@GET
@Path("/{indexName}/mapping")
public jakarta.ws.rs.core.Response getIndexMapping(@PathParam("indexName")
 String indexName)

Returns the field mapping of the named index as JSON.

The protobuf mapping struct is rendered to JSON and parsed back into a map for the response. A serialization failure is logged and reported as a 500.

Parameters:

indexName - the index whose mapping is requested

Returns:

a 200 JSON response with indexName and mappings, a 500 on serialization failure, or an error response

createIndex

@POST
public jakarta.ws.rs.core.Response createIndex(Map<String,Object> payload)

Creates a kNN vector index.

The request body must supply indexName and dimensions (there is no default for dimensions); fieldName is optional and defaults to embeddings. Missing required fields yield a 400.

Parameters:

payload - request body with indexName, dimensions, and optional fieldName

Returns:

a 200 JSON response describing the created index, a 400 on missing required fields, or an error response

provisionIndex

@POST
@Path("/provision")
public jakarta.ws.rs.core.Response provisionIndex(Map<String,Object> payload)

Pre-provisions a fresh parent index plus every --chunk-- / --vs-- side index required by the supplied SemanticConfigs, and populates the vector_set_index_binding cache. After this call returns success=true, documents indexed into indexName take the cached fast path — no per-doc DB writes or cluster-state round-trips.

This is the stress-test-friendly setup step: call it once with a scratch index name before firing a stress run that targets opensearch-sink, then use deprovisionIndex(Map) to tear down when the run is complete.

Idempotent. Safe to re-invoke with the same inputs.

Request body: { "indexName": "...", "semanticConfigIds": [...] }

Response body: success, indicesCreated[], bindingsProvisioned, message

Parameters:

payload - request body with indexName and optional semanticConfigIds

Returns:

provisioning outcome

deprovisionIndex

@POST
@Path("/deprovision")
public jakarta.ws.rs.core.Response deprovisionIndex(Map<String,Object> payload)

Tears down a previously-provisioned index set: deletes the parent index plus every index whose name starts with indexName + "--" (the OSM convention for --chunk--… and --vs--… side indices). Composed from the existing ListIndices + DeleteIndex RPCs — OSM does not yet have a matched DeprovisionIndex counterpart, so this is a best-effort loop that keeps going past individual failures and reports what it did.

Binding rows (vector_set_index_binding) are not dropped here — only the OpenSearch indices. Binding cleanup still requires direct DB surgery until OSM ships RemoveSemanticBinding (TODO in OpenSearchManagerService).

Same safety fence as deleteIndex(String, boolean): refuses to operate on indices outside test-pipeline-* / pipeline-* / test-* prefixes unless force=true.

Parameters:

payload - request body with indexName and optional force

Returns:

deprovisioning outcome (requested / deleted / failures)

deleteIndex

@DELETE
@Path("/{indexName}")
public jakarta.ws.rs.core.Response deleteIndex(@PathParam("indexName")
 String indexName,
 @QueryParam("force") @DefaultValue("false")
 boolean force)

Deletes a single index.

Unless force is set, only test-pipeline-* and pipeline-* indices may be deleted; other names are rejected with a 403.

Parameters:

indexName - the index to delete

force - when true, bypasses the test-prefix safety restriction

Returns:

a 200 JSON response with the deletion outcome, a 403 when the safety restriction blocks the request, or an error response

getDocument

@GET
@Path("/{indexName}/documents/{documentId}")
public jakarta.ws.rs.core.Response getDocument(@PathParam("indexName")
 String indexName,
 @PathParam("documentId")
 String documentId)

Fetches a single stored document by index and document id.

When the document is not found a 404 is returned; otherwise the stored document is rendered to JSON (preserving proto field names) and returned.

Parameters:

indexName - the index to read from

documentId - the id of the document to fetch

Returns:

a 200 JSON document when found, a 404 when not found, a 500 on serialization failure, or an error response