Skip to main content

Documents API

Documents are the individual records stored in a collection. This page covers create, read, update, delete, and bulk operations.

Add Document​

Insert a document into a collection.

Endpoint: POST /collections/{name}/documents

Path Parameters​

ParameterTypeRequiredDescription
namestringYesCollection name

Request Body​

JSON object with document fields matching the collection schema.

Example Request​

curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "product1",
    "title": "Laptop Computer",
    "description": "High-performance laptop with 16GB RAM",
    "price": 1299.99,
    "category": "Electronics",
    "in_stock": true
  }'

Example Response​

{
  "message": "Document added successfully",
  "id": "product1"
}

Auto-Generated ID​

If id is omitted, hlquery generates one automatically:

curl -X POST http://localhost:9200/collections/products/documents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wireless Mouse",
    "price": 29.99
  }'

Response will include the auto-generated ID.

Get Document​

Retrieve a specific document by ID.

Endpoint: GET /collections/{name}/documents/{id}

Path Parameters​

ParameterTypeRequiredDescription
namestringYesCollection name
idstringYesDocument ID

Query Parameters​

ParameterTypeRequiredDefaultDescription
include_created_atbooleanNofalseIf true, includes created_at field (ISO 8601 format) in the response

Example Request​

curl "http://localhost:9200/collections/products/documents/product1?include_created_at=true"

Example Response​

{
  "id": "product1",
  "title": "Laptop Computer",
  "description": "High-performance laptop with 16GB RAM",
  "price": 1299.99,
  "category": "Electronics",
  "in_stock": true
}

Get Document Context​

Retrieve context around a specific document.

Endpoint: GET /collections/{name}/documents/{id}/context

Path Parameters​

ParameterTypeRequiredDescription
namestringYesCollection name
idstringYesDocument ID

Example Request​

curl "http://localhost:9200/collections/products/documents/product1/context"

This endpoint is useful for interfaces that need surrounding document context after a search hit.

List Documents​

List all documents in a collection with pagination.

Endpoint: GET /collections/{name}/documents

Query Parameters​

ParameterTypeRequiredDefaultMaxDescription
offsetintegerNo0-Number of documents to skip
limitintegerNo10250Maximum number of documents to return
include_created_atbooleanNofalse-If true, includes created_at field (ISO 8601 format) for each document

Example Request​

curl "http://localhost:9200/collections/products/documents?offset=0&limit=10&include_created_at=true"

Example Response​

{
  "documents": [
    {
      "id": "product1",
      "title": "Laptop Computer",
      "price": 1299.99
    },
    {
      "id": "product2",
      "title": "Wireless Mouse",
      "price": 29.99
    }
  ],
  "found": 150,
  "offset": 0,
  "limit": 10
}

Update Document​

Update an existing document. This performs a partial update - only provided fields will be updated.

Endpoint: PUT /collections/{name}/documents/{id}

Request Body​

JSON object with fields to update. Only include fields that need to be changed.

Example Request​

curl -X PUT http://localhost:9200/collections/products/documents/product1 \
  -H "Content-Type: application/json" \
  -d '{
    "price": 1199.99,
    "description": "High-performance laptop with 32GB RAM and 1TB SSD"
  }'

Example Response​

{
  "message": "Document updated successfully",
  "id": "product1"
}

Note: If the document doesn't exist, it will be created (upsert behavior).

Delete Document​

Delete a specific document.

Endpoint: DELETE /collections/{name}/documents/{id}

Example Request​

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

Example Response​

{
  "message": "Document deleted successfully",
  "id": "product1"
}

Delete Documents by Filter​

Delete multiple documents matching a filter condition.

Endpoint: DELETE /collections/{name}/documents

Query Parameters​

ParameterTypeRequiredDescription
filter_bystringYesFilter condition (e.g., category:Electronics)

Example Request​

curl -X DELETE "http://localhost:9200/collections/products/documents?filter_by=category:Electronics"

Example Response​

{
  "message": "Documents deleted successfully",
  "deleted_count": 42
}

Warning: This operation permanently deletes all matching documents. Use with caution.

Update Documents by Query​

Update multiple documents matching a query or filter.

Endpoint: POST /collections/{name}/documents/_update_by_query

Example Request​

curl -X POST http://localhost:9200/collections/products/documents/_update_by_query \
  -H "Content-Type: application/json" \
  -d '{
    "filter_by": "category:Electronics",
    "set": {
      "featured": true
    }
  }'

Warning: This operation can modify many documents. Test the filter with search first.

Delete Documents by Query​

Delete multiple documents matching a query or filter.

Endpoint: POST /collections/{name}/documents/_delete_by_query

Example Request​

curl -X POST http://localhost:9200/collections/products/documents/_delete_by_query \
  -H "Content-Type: application/json" \
  -d '{
    "filter_by": "discontinued:true"
  }'

Warning: This operation permanently deletes all matching documents. Test the filter with search first.

Bulk Import Documents​

Import multiple documents at once for better performance.

Endpoint: POST /collections/{name}/documents/import

Request Body​

JSON array of documents, or newline-delimited JSON (NDJSON).

Example Request (JSON Array)​

curl -X POST http://localhost:9200/collections/products/documents/import \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "product1",
      "title": "Laptop",
      "price": 1299.99
    },
    {
      "id": "product2",
      "title": "Mouse",
      "price": 29.99
    }
  ]'

Example Request (NDJSON)​

curl -X POST http://localhost:9200/collections/products/documents/import \
  -H "Content-Type: application/x-ndjson" \
  -d '{"id":"product1","title":"Laptop","price":1299.99}
{"id":"product2","title":"Mouse","price":29.99}'

Example Response​

{
  "message": "Documents imported successfully",
  "imported_count": 2,
  "failed_count": 0
}

Tip: Use bulk import for adding many documents - it's much faster than adding them one by one.

Document Fields​

Documents can contain various field types:

String Fields​

{
  "title": "Product Name",
  "description": "Product description text"
}

Field Value Character Restrictions

String field values have character restrictions to ensure proper parsing and indexing:

Invalid Characters (not allowed in field values):

  • Commas (,) - Reserved for internal parsing

Valid Characters (allowed in field values):

  • Letters (a-z, A-Z)
  • Numbers (0-9)
  • Underscores (_)
  • Hyphens (-)
  • Spaces
  • Periods (.)
  • Most punctuation marks (except commas)

Examples:

Valid:

{
  "tags": "tag1_tag2_tag3",
  "cast": "Actor1_Actor2_Actor3",
  "genre": "Action_Drama"
}

Invalid:

{
  "tags": "tag1,tag2,tag3",
  "cast": "Actor1, Actor2",
  "genre": "Action,Drama"
}

Workarounds:

  • Use underscores (_) or spaces instead of commas
  • Use arrays for multiple values: "tags": ["tag1", "tag2", "tag3"]
  • Use separate fields if you need comma-separated data

Numeric Fields​

{
  "price": 1299.99,
  "quantity": 42
}

Boolean Fields​

{
  "in_stock": true,
  "featured": false
}

Array Fields​

{
  "tags": ["electronics", "computers", "laptops"],
  "categories": ["Electronics", "Computers"]
}

Object Fields​

{
  "metadata": {
    "created_by": "admin",
    "created_at": "2024-01-15",
    "version": 1
  }
}

Document ID​

Document IDs must follow these rules:

RuleDescriptionExample
UniquenessUnique within a collectionproduct1
Length1-64 charactersuser_123
CharactersAlphanumeric, underscores, hyphensitem-2024-01

Valid IDs​

  • product1
  • user_123
  • item-2024-01

Invalid IDs​

  • Product 1 (spaces not allowed)
  • product@1 (special characters not allowed)

Best Practices​

  1. Use meaningful IDs: Choose descriptive, unique IDs
  2. Batch operations: Use bulk import for adding many documents
  3. Partial updates: Only send fields that need updating
  4. Validate data: Ensure document fields match collection schema
  5. Handle errors: Check response status codes and error messages

Error Handling​

Document Not Found​

Status Code: 404 Not Found

{
  "error": "Document not found",
  "id": "nonexistent"
}

Invalid Document Data​

Status Code: 400 Bad Request

{
  "error": "Invalid document data",
  "message": "Field 'price' must be a number"
}

Invalid Characters in Field Values​

Status Code: 400 Bad Request

If you include commas or other invalid characters in string field values, you'll receive:

{
  "error": "Parse error: Invalid content value: Field values cannot contain commas",
  "collection": "products"
}

Common causes:

  • Using commas in field values (e.g., "tags": "tag1,tag2,tag3")
  • Copy-pasting CSV data directly into field values

Solution: Replace commas with underscores, spaces, or use arrays:

  • "tags": "tag1_tag2_tag3"
  • "tags": ["tag1", "tag2", "tag3"]

Collection Not Found​

Status Code: 404 Not Found

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

Next Steps​