REST API Endpoints

This topic describes the VMware GemFire Vector Database REST API endpoints.

Using the Commands

{baseUri}

For all of the below commands, “{baseUri}” is in the form:

http://<HOSTNAME>:<PORT-NUMBER>/gemfire-vectordb/v1

Where:

<HOSTNAME> is the name or IP address of the host machine running your GemFire server.
<PORT-NUMBER> is the port number specified by http-service-port when the GemFire server was started.

If you run more than one server with the same VMware GemFire Vector Database, the index is partitioned across all of the servers and “{baseUri}” can reference any of them.

Accessing Secure Clusters with Enhanced Security

If your GemFire cluster employs a security manager, you must authenticate securely using valid credentials. However, sensitive information like usernames and passwords should never be sent over unencrypted connections such as standard HTTP.

To access the server through the REST interface securely, use HTTPS. HTTPS encrypts all data transmitted between the client and server, preventing any interception or tampering of data.

Structure your request URL as follows:

https://<HOSTNAME>:<PORT-NUMBER>/gemfire-vectordb/v1

Where:

<HOSTNAME> is the name or IP address of the host machine running your GemFire server.
<PORT-NUMBER> is the port number specified by http-service-port when the GemFire server was started.

Authentication

Do not include your username and password in the URL. Instead, use a secure method of authentication such as HTTP Basic Authentication headers or OAuth tokens.

For HTTP Basic Authentication, for example, encode your username:password in Base64 and include it in the Authorization header of your HTTP request:

Authorization: Basic <Base64-encoded credentials>

Where <Base64-encoded credentials> is your Base64-encoded username and password combination.

VMware recommends that you always consult your security administrator or refer to your GemFire cluster’s security guidelines to choose the most secure authentication method in line with your organizational protocols.

Index Management

Create Index

Creates and configures an index to be used for similarity search.

URL: POST {baseUri}/indexes
Status: 201 Created

Request Body:

{
  "name": string,
  "beam-width": integer,
  "max-connections": integer,
  "vector-similarity-function": "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT" | "MAXIMUM_INNER_PRODUCT",
  "fields": array of strings,
  "buckets": integer
}

Response Body:

none

Parameters for `create index`

Name	Type	Description	Default
name	String	The name of the vector index.
beam-width	Integer	Optional. The number of nearest neighbors to consider during index updates. Larger beam-width values may result in slower indexing but with more accurate results. Maximum: `3200`	`100`
max-connections	Integer	Optional. The maximum number of nearest neighbors that are connected to each node in the Hierarchical Navigable Small World (HNSW) graph. Determines how many neighbors a node can have. Higher values can improve recall when working with higher dimensional data but use more memory. Maximum: `512`	`16`
vector-similarity-function	String	Optional. Distance metric to use for vector similarity. Valid values: `COSINE`, `DOT_PRODUCT`, `EUCLIDEAN`, `MAXIMUM_INNER_PRODUCT`.	`COSINE`
fields	Array of strings	Optional. Array of field names to index, expected to be present in embedding metadata when added.
buckets	Integer	Optional. Indexes and their embeddings are partitioned across the number of specified buckets. Each search computes similarity searches across an index’s buckets, returning the `k-per-bucket` number of results and combining them to return the `top-k` results. If this number is greater than the number of servers, some severs will host more than one bucket. Because each bucket is queried, this can lead to slower query speed.	The number of servers available when creating the index.

Details:

create index internally creates a GemFire region that asynchronously updates a Hierarchical Navigable Small World (HNSW) graph. This region is created with the following attributes:

name is the same as the name of the index. If a region with the index name already exists, create index will use that region.
Non-persistent
HEAP_LRU: overflow
Redundant

Delete Index

Deletes the specified vector index, its embeddings, and the underlying GemFire region, unless otherwise specified.

URL: DELETE {baseUri}/indexes/{indexName}
Status: 204 No Content

Request Body:

{
  "delete-data": boolean
}

Response Body:

none

Parameters for `delete index`

Name	Type	Description	Default
delete-data	Boolean	Optional. Whether or not to delete the underlying GemFire region. If `false`, the index is deleted, but the GemFire region is not deleted and retains all embedding data. To use this region and data for vector queries, it must be reindexed.	`true`

Get Index

Returns detailed information about the specified vector index.

URL: GET {baseUri}/indexes/{indexName}
Status: 200 OK

Request Body:

none

Response Body:

{
  "name": string,
  "beam-width": integer,
  "max-connections": integer,
  "vector-similarity-function": "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT" | "MAXIMUM_INNER_PRODUCT",
  "buckets": integer,
  "number-of-embeddings": integer
}

List Indexes

Returns a list of all vector indexes.

URL: GET {baseUri}/indexes
Status: 200 OK

Request Body:

none

Response Body:

[
  {
    "name": string,
    "beam-width": integer,
    "max-connections": integer,
    "vector-similarity-function": "COSINE" | "EUCLIDEAN" | "DOT_PRODUCT" | "MAXIMUM_INNER_PRODUCT",
    "buckets": integer,
    "number-of-embeddings": integer
  },
  ...
]

Update Index

Potentially improves query performance by force merging the underlying index segments. This operation is very CPU intensive and can take long amounts of time based on the number of embeddings in the index.

URL: POST {baseUri}/indexes/{indexName}
Status: 204 No Content

Request Body:

{
  "optimize": boolean
}

Response Body:

none

Parameters for `update index`

Name	Type	Description	Default
optimize	Boolean	Optional. Updates the index to potentially improve query performance.	`true`

Embeddings

Add Embeddings

Adds or updates embeddings.

URL: POST {baseUri}/indexes/{indexName}/embeddings
Status: 204 No Content

Request Body:

[
  {
    "key": string,
    "vector": [
      float,
      float,
      float,
      ...
    ],
    "metadata": {
      "field": "value",
      ...
    }
  },
  ...
]

Response Body:

none

Parameters for `add embeddings`

Name	Type	Description	Default
key	String	Optional. Unique ID of the embedding.	An autogenerated UUID.
vector	Array of floats	The embedding vector of float values. Must match the dimension of the index. See details below for more information.
metadata	JSON object	Optional. Data stored and indexed with the vector and optionally retrieved while searching embeddings.

Details:

The first embedding added to the index sets the dimension of the index. If attempt to add embeddings with a dimension other than that of the index, the embeddings are not added to the index but persist in GemFire.

Delete Embeddings

Deletes one or more embeddings using the embeddings key.

URL: DELETE {baseUri}/indexes/{indexName}/embeddings
Status: 204 No Content

Request Body:

[
  string,
  string,
  ...
]

Response Body:

none

Parameters for `delete embeddings`

Name	Type	Description	Default
	Array of strings	Each element of the supplied array matches an embedding key value to be deleted.

Get Embedding

Returns the embedding associated with the specified key.

URL: GET {baseUri}/indexes/{indexName}/embeddings/{key}
Status: 200 OK

Request Body:

none

Response Body:

{
  "key": string,
  "metadata": json_object,
  "vector": [
    float,
    float,
    float,
    ...
  ]
}

Search Embeddings

Searches the embeddings and returns the closest top-k matches.

URL: POST {baseUri}/indexes/{indexName}/query
Status: 200 OK

Request Body:

{
  "vector": [
    float,
    float,
    float,
    ...
  ],
  "top-k": integer,
  "k-per-bucket": integer,
  "include-metadata": boolean
}

Response Body:

[
  {
    "key": string,
    "score": float,
    "metadata": json_object
  },
  ...
]

Parameters for `search embeddings`

Name	Type	Description	Default
vector	Array of floats	Embedding vector to search for.
top-k	Integer	Optional. Maximum number of results to return.	`10`
k-per-bucket	Integer	Optional. Number of intermediate results per bucket to find during search. Setting this number higher may provide more accurate results but could result in lower performance. See details below for more information.	Value of `top-k`.
include-metadata	Boolean	Optional. Include metadata stored with embedding, if present.	`false`

Details:

VMware recommends that k-per-bucket should not be set higher than top-k. If k-per-bucket is set higher than top-k, the results from each bucket are aggregated and only the top-k results are returned.

Reducing the value of k-per-bucket increases querying speed, but can produce less accurate results if most of the top data resides in specific buckets.

Using the Commands

{baseUri}

Accessing Secure Clusters with Enhanced Security

Authentication

Index Management

Create Index

Parameters for create index

Details:

Delete Index

Parameters for delete index

Get Index

List Indexes

Update Index

Parameters for update index

Embeddings

Add Embeddings

Parameters for add embeddings

Details:

Delete Embeddings

Parameters for delete embeddings

Get Embedding

Search Embeddings

Parameters for search embeddings

Details:

Parameters for `create index`

Parameters for `delete index`

Parameters for `update index`

Parameters for `add embeddings`

Parameters for `delete embeddings`

Parameters for `search embeddings`