Kikiola provides the following API endpoints:
POST /vectors
: Insert a new vectorGET /vectors/{id}
: Retrieve a vector by IDDELETE /vectors/{id}
: Delete a vector by IDPATCH vectors/{id}/metadata
: Update the metadata of a vectorGET /query/{id}
: Retrieve the original text content associated with an embedding IDPOST /search
: Search for the nearest neighbours of a vectorPOST /objects
: Insert a new object (e.g., document, image, audio, video, or any other file type)GET /objects/{id}
: Retrieve an object by IDDELETE /objects/{id}
: Delete an object by IDPATCH /objects/{id}/metadata
: Update the metadata of an objectPATCH /objects/{id}/content
: Update the content of an object by uploading a new file
Here are some examples of how to use Kikiola with cURL:
- Insert a new vector:
curl -X POST -H "Content-Type: application/json" -d '{
"id": "badf35f6-e291-46cb-986b-01d57e6df80b",
"embedding": [0.1, 0.2, 0.3],
"metadata": {
"name": "Vector 1",
"category": "sample"
}
}' http://localhost:3400/vectors
- Retrieve a vector by ID:
curl -X GET http://localhost:3400/vectors/badf35f6-e291-46cb-986b-01d57e6df80b
- Delete a vector by ID:
curl -X DELETE http://localhost:3400/vectors/badf35f6-e291-46cb-986b-01d57e6df80b
- Search for the nearest neighbours of a vector:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"id": "query_vector",
"embedding": [0.5, 0.6, 0.7]
},
"k": 5
}' http://localhost:3400/search
- Tensor Compression:
curl -X POST -H "Content-Type: application/json" -d '{
"id": "f5fbc794-c23a-4924-85af-775d4d34ecde",
"embedding": [0.1, 0.2, 0.3],
"metadata": {
"name": "Tensor Compression",
"category": "sample"
},
"compressed": true,
"quantizationParams": {
"min": -1.0,
"max": 1.0,
"bits": 8
},
"pruningMask": [false, true, false],
"sparseIndices": [0, 2]
}' http://localhost:3400/vectors
- Bioinformatics — Storing and Analysing Gene Sequences:
curl -X POST -H "Content-Type: application/json" -d '{
"id": "badf35f6-e291-46cb-862d-01d57e6df80b",
"embedding": [
1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1,
1, 0, 0, 0,
0, 1, 0, 0,
0, 0, 1, 0,
0, 0, 0, 1
], // Placeholder for the actual embedding
"metadata": {
"name": "Gene Sequence 1",
"category": "gene",
"sequence": "ACGTACGT" // Placeholder for the actual gene sequence
}
}' http://localhost:3400/vectors
- Retrieve the original text content associated with an embedding ID:
curl -X GET "http://localhost:3400/query/83635f86-56b3-4bdd-a9bf-428dcebb8674"
- Update the metadata of a vector:
curl -X PATCH "http://localhost:3400/vectors/83635f86-56b3-4bdd-a9bf-428dcebb8674/metadata" -H "Content-Type: application/json" -d '{"metadata": {"name": "PDF Embeddings", "category": "pdf"}}'
- Hybrid search (combining sparse embedding and traditional keyword search):
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3],
"Metadata": {"text": "search keywords"}
},
"k": 10
}' http://localhost:3400/search
- Reranking of search results:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3]
},
"k": 10,
"rerank": true
}' http://localhost:3400/search
- Setting Alpha value (influence factor) for hybrid search:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3],
"Metadata": {"text": "search keywords"}
},
"k": 10,
"alpha": 0.7
}' http://localhost:3400/search
- Support for more distance/similarity metrics beyond just cosine similarity:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3]
},
"k": 10,
"metric": "euclidean"
}' http://localhost:3400/search
- ANN (Approximate Nearest Neighbor) indexing for faster search on large datasets:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.02329646609723568, -0.044301047921180725, -0.014636795036494732]
},
"k": 10,
"indexType": "annoy",
"params": {
"n_trees": 10
}
}' http://localhost:3400/search
- Ability to explain individual search results:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3]
},
"k": 10,
"explain": true
}' http://localhost:3400/search
- Customizable relevance tuning and boosting of results:
curl -X POST -H "Content-Type: application/json" -d '{
"vector": {
"ID": "query_vector",
"Embedding": [0.1, 0.2, 0.3]
},
"k": 10,
"boost": {
"category": "sample",
"weight": 2.0
}
}' http://localhost:3400/search
- Insert a new object:
curl -X POST -H "Content-Type: multipart/form-data" -F "data={
\"id\": \"0539f0ac-6771-47c6-8f5e-2cdf272a6de0\",
\"metadata\": {
\"name\": \"Oxford\",
\"category\": \"Image\"
}
};type=application/json" -F "[email protected]" http://localhost:3400/objects
- Retrieve an object by ID:
curl -X GET http://localhost:3400/objects/0539f0ac-6771-47c6-8f5e-2cdf272a6de0
- Delete an object by ID:
curl -X DELETE http://localhost:3400/objects/0539f0ac-6771-47c6-8f5e-2cdf272a6de0
- PATCH an object metadata by ID:
curl -X PATCH -H "Content-Type: application/json" -d '{
"metadata": {
"name": "Oxford High Street",
"category": "Images"
}
}' http://localhost:3400/objects/0539f0ac-6771-47c6-8f5e-2cdf272a6de0/metadata
- PATCH an object content with a new one by ID:
curl -X PATCH -H "Content-Type: multipart/form-data" -F "object=@oxford_high_street.webp" http://localhost:3400/objects/0539f0ac-6771-47c6-8f5e-2cdf272a6de0/content
To use Kikiola in your Go applications or systems, follow these steps:
- Install Kikiola as a dependency:
go get github.com/0xnu/kikiola
- Import the necessary packages in your Go code:
import (
"github.com/0xnu/kikiola/pkg/db"
"github.com/0xnu/kikiola/pkg/server"
)
- Create a new storage instance and server:
storage, err := db.NewStorage("data/vectors.db")
if err != nil {
log.Fatal(err)
}
defer storage.Close()
server := server.NewServer(storage)
- Start the Kikiola server:
log.Fatal(server.Start(":9090"))
Now, you can use Kikiola's functionality in your application or system by making HTTP requests to the appropriate endpoints.
Follow the tutorials below to integrate Kikiola and vector search into your current application.