Collections API

Collections are schema containers for documents, similar to tables in relational systems. This page covers collection lifecycle operations.

---

List Collections

List all collections.

Endpoint: GET /collections

Query Parameters

Parameter	Type	Required	Default	Description
offset	integer	No	0	Number of collections to skip (pagination)
limit	integer	No	all	Maximum number of collections to return (pagination)
pattern	string	No	-	Wildcard pattern to filter collection names (supports * and ?)
sort_by	string	No	name:asc	Sort by name, num_documents, or created_at with :asc or :desc
maybe_min	integer	No	disabled	Include maybe suggestions when filtered results are below threshold
maybe_limit	integer	No	5	Max number of collection-name suggestions
maybe	string	No	-	Shorthand maybe=<min>,<limit>

Example Request

curl http://localhost:9200/collections

Example Response

{
  "collections": [
    {
      "name": "products",
      "num_documents": 150,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "name": "articles",
      "num_documents": 42,
      "created_at": "2024-01-14T08:15:00Z"
    }
  ]
}

With Pagination

curl "http://localhost:9200/collections?offset=0&limit=10"

With Wildcard Pattern

curl "http://localhost:9200/collections?pattern=prod*"

Sort Results

# Sort by document count descending
curl "http://localhost:9200/collections?sort_by=num_documents:desc"

---

List Collections (Distributed)

List collections across all configured cluster nodes.

Endpoint: GET /collections/distributed

Query Parameters

Parameter	Type	Required	Default	Description
offset	integer	No	0	Number of collections to skip (pagination)
limit	integer	No	all	Maximum number of collections to return (pagination)
pattern	string	No	-	Wildcard pattern to filter collection names (supports * and ?)
sort_by	string	No	name:asc	Sort by name (other fields are local-only)

Example Request

curl "http://localhost:9200/collections/distributed?pattern=prod*&sort_by=name:asc"

Example Response

{
  "status": "ok",
  "nodes": ["127.0.0.1:9200", "127.0.0.1:9201"],
  "node_count": 2,
  "collections": [
    {
      "name": "products",
      "nodes": ["127.0.0.1:9200", "127.0.0.1:9201"]
    }
  ],
  "total": 1,
  "errors": []
}

Create Collection

Create a new collection with a defined schema.

Endpoint: POST /collections

Request Body

{
  "name": "collection_name",
  "fields": [
    {
      "name": "field_name",
      "type": "string|int32|float|bool|string[]|float[]|geo_point"
    }
  ],
  "default_sorting_field": "field_name"
}

Field Types

Type	Description	Example
string	Text field (searchable by default)	"title": "Laptop"
int32	32-bit integer	"quantity": 10
float	Floating-point number	"price": 99.99
bool	Boolean value	"in_stock": true
string[]	Array of strings	"tags": ["laptop", "computer"]
float[]	Array of floats (for vectors)	"embedding": [0.1, 0.2, 0.3]
geo_point	Latitude/longitude point for geo filters and distance sorting	"location": [40.7128, -74.0060]

Geo field type aliases are accepted as geo_point, geopoint, geo, and latlon. Documents may store geo points as [lat, lon], { "lat": 40.7128, "lon": -74.0060 }, { "latitude": 40.7128, "longitude": -74.0060 }, or a string such as "40.7128,-74.0060".

Example Request

curl -X POST http://localhost:9200/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "description", "type": "string"},
      {"name": "price", "type": "float"},
      {"name": "category", "type": "string"},
      {"name": "tags", "type": "string[]"},
      {"name": "in_stock", "type": "bool"}
    ],
    "default_sorting_field": "price"
  }'

Example Response

{
  "message": "Collection created successfully",
  "name": "products"
}

Alternative: Using searchable_fields

{
  "name": "products",
  "searchable_fields": ["title", "description"],
  "fields": [
    {"name": "price", "type": "float"},
    {"name": "category", "type": "string"}
  ]
}

---

Get Collection

Get detailed information about a specific collection.

Endpoint: GET /collections/{name}

Path Parameters

Parameter	Type	Required	Description
name	string	Yes	Collection name

Example Request

curl http://localhost:9200/collections/products

Example Response

{
  "name": "products",
  "num_documents": 150,
  "created_at": "2024-01-15T10:30:00Z",
  "fields": [
    {
      "name": "title",
      "type": "string",
      "facet": false,
      "optional": false
    },
    {
      "name": "price",
      "type": "float",
      "facet": false,
      "optional": false
    }
  ],
  "default_sorting_field": "price"
}

---

Update Collection

Update a collection's schema.

Note: You can only add new fields, not remove or modify existing ones.

Endpoint: POST /collections/{name}/update

Request Body

{
  "fields": [
    {
      "name": "new_field",
      "type": "string"
    }
  ]
}

Example Request

curl -X POST http://localhost:9200/collections/products/update \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {"name": "brand", "type": "string"}
    ]
  }'

Example Response

{
  "message": "Collection updated successfully",
  "name": "products"
}

---

Delete Collection

Delete a collection and all its documents.

Endpoint: DELETE /collections/{name}

Example Request

curl -X DELETE http://localhost:9200/collections/products

Example Response

{
  "message": "Collection deleted successfully"
}

Warning: This operation is irreversible. All documents in the collection will be permanently deleted.

---

Collection Naming Rules

Collection names must follow these rules:

Rule	Description	Example
Length	1-64 characters	products
Characters	Alphanumeric, underscores (_), hyphens (-)	user_profiles
Start	Letter or number	blog-posts
Uniqueness	Unique within the server	products_2024

Valid Names

• products
• user_profiles
• blog-posts
• products_2024

Invalid Names

• Products (case-sensitive, but lowercase recommended)
• my collection (spaces not allowed)
• 123collection (can start with number, but not recommended)
• collection@name (special characters not allowed)

---

Best Practices

1. Plan your schema: Think about your search needs before creating collections
2. Use descriptive names: Choose clear, descriptive collection names
3. Define searchable fields: Explicitly mark which fields should be searchable
4. Set default sorting: Specify a default sorting field for better performance
5. Use appropriate types: Choose the right field type for your data

---

Error Handling

Collection Already Exists

Status Code: 409 Conflict

{
  "error": "Collection already exists",
  "name": "products"
}

Collection Not Found

Status Code: 404 Not Found

{
  "error": "Collection not found",
  "name": "nonexistent"
}

Invalid Schema

Status Code: 400 Bad Request

{
  "error": "Schema validation failed",
  "message": "Field 'price' must have a valid type"
}

---

Next Steps

• Learn about Documents API to add data to your collections
• Explore Search API to query your collections
• Check out Synonyms and Stopwords for enhanced search