Create a new Collection

At the time of writing, the OramaCore APIs are in beta. We can guarantee that the APIs will change in a way that breaks existing applications.

We will make these APIs stable in the v1.0.0 release, planned for February 28th, 2025.

We can think of collections as a way to group documents together.

For example, if you want to index all the products in your e-commerce store, you might want to create a collection called products, where each document represents a single product.

APIs

API Key type: master.

Creating a new collection is as simple as:

curl -X POST \
  http://localhost:8080/v0/collections \
  -H 'Authorization: Bearer <master-api-key>' \
  -d '{
    "id": "products",
    "write_api_key": "my-write-api-key",
    "read_api_key": "my-read-api-key"
  }'

A more complete example, with all the optional fields:

curl -X POST \
  http://localhost:8080/v0/collections \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <master-api-key>' \
  -d '{
    "id": "products",
    "write_api_key": "my-write-api-key",
    "read_api_key": "my-read-api-key",
    "description": "My optional description about this collection of products",
    "language": "english",
    "embeddings": {
      "model": "BGESmall",
      "document_fields": ["title", "description"]
    }
  }'

In the next sections, we'll explain each of the parameters in detail.

Parameters

Name	Type	Description	Required	Default
`id`	`string`	The id of the collection.	Yes	-
`write_api_key`	`string`	The write API key for this collection.	Yes	-
`read_api_key`	`string`	The read API key for this collection.	Yes	-
`description`	`string`	A description for this collection.	No	-
`language`	`string`	The language of the documents in this collection.	No	`english`
`embeddings`	`object`	The configuration for text embeddings.	No	-

The embeddings object is the parameter used by OramaCore to configure text embeddings generation for the documents in this collection.

The embeddings object has the following parameters:

Name	Type	Description	Required	Default
`model`	`string`	The model to use for text embeddings generation.	No	`MultilingualE5Small`
`document_fields`	`string[]`	The fields to use for text embeddings generation. If not specified, OramaCore will use all the string fields found in the documents.	No	-

Read more about text embeddings and their configurations here.

Hooks

After creating a collection, you can start using some hooks. If you're not familiar with hooks, you can read more about them in the Hooks section.

At the time of writing, we have the following hooks available:

selectEmbeddingProperties: Allows you to programmatically select properties for text extraction during text embeddings generation.
curl -X POST http://localhost:8080/{COLLECTION_ID}/v0/hooks/add \ -H 'Content-Type: application/json' \ -d '{ "id": "selectEmbeddingProperties", "code": "function selectEmbeddingProperties(document) { return document.title; }" }'
Read more about this hook here.

Create a new Collection

APIs

Parameters

Hooks

On this page