Back
Documentation
PlaygroundDashboard

QuartzDB Documentation

QuartzDB is a serverless vector database built on Cloudflare Workers. It provides fast semantic search using the HNSW algorithm with zero cold starts.

What is a Vector Database?
A vector database stores numerical representations (embeddings) of data like text, images, or audio. It enables semantic search - finding similar items based on meaning, not just keywords.
REST API
Simple HTTP endpoints
HNSW Search
Sub-millisecond queries
Durable Storage
Persistent vectors

Getting an API Key

Current Status: QuartzDB is in private beta. API keys are issued manually by administrators.

How to Request Access

  1. Contact the administrator - Email or message the QuartzDB team with your use case
  2. Receive your API key - You'll get a 64-character hexadecimal key
  3. Store it securely - Save the key in environment variables, never commit to git
  4. Start using the API - Include the key in the X-API-Key header

API Key Format

API keys are 64-character hexadecimal strings:

text
8d9f52035876a6ade379a6f5208d34e0849bdf44e1ba58417e4bef821537232e

Security Best Practices

  • Never share your API key publicly
  • Use environment variables to store keys
  • Rotate keys periodically
  • Use different keys for development and production

Authentication

All API endpoints (except /health) require an API key. Include your key in the X-API-Key header.

Example Request

bash
# Replace YOUR_API_KEY with your actual key
curl -s "https://api.quartzdb.io/api/vector/stats" \
  -H "X-API-Key: YOUR_API_KEY"

# Example with actual key format:
curl -s "https://api.quartzdb.io/api/vector/stats" \
  -H "X-API-Key: 8d9f52035876a6ade379a6f5208d34e0849bdf44e1ba58417e4bef821537232e"

Expected Response (Success)

json
{
  "success": true,
  "algorithm": "HNSW",
  "dimension": 384,
  "num_vectors": 42,
  "num_active": 40,
  "num_deleted": 2,
  "deletion_ratio_percent": "4.8",
  "recommendation": "Healthy: <10% vectors deleted"
}

Error Response (Invalid Key)

text
Unauthorized: Invalid or missing API key

Quick Start

All examples below use a sample 384-dimensional vector. In production, you would generate vectors using an embedding model (see Creating Embeddings).
1

Check the service is running

No authentication required for health check:

bash
curl -s "https://api.quartzdb.io/health" | jq .

Expected Response

json
{
  "status": "healthy",
  "service": "quartz-faas",
  "version": "0.1.0",
  "uptime_seconds": 3600,
  "checks": {
    "storage": "ok",
    "vector_index": "ok"
  }
}
2

Insert a vector

Insert a vector with a unique ID and optional metadata. The vector must be exactly 384 dimensions.

bash
# Set your API key
export API_KEY="YOUR_API_KEY"

# Insert a vector (384 dimensions required)
curl -s -X POST "https://api.quartzdb.io/api/vector/insert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "id": "doc_quickstart_1",
    "vector": [0,0.002617,0.005234,0.007851,0.010468,0.013085,0.015702,0.018319,0.020936,0.023553,0.02617,0.028787,0.031404,0.034021,0.036638,0.039255,0.041872,0.044489,0.047106,0.049723,0.05234,0.054957,0.057574,0.060191,0.062808,0.065425,0.068042,0.070659,0.073276,0.075893,0.07851,0.081127,0.083744,0.086361,0.088978,0.091595,0.094212,0.096829,0.099446,0.102063,0.10468,0.107297,0.109914,0.112531,0.115148,0.117765,0.120382,0.122999,0.125616,0.128233,0.13085,0.133467,0.136084,0.138701,0.141318,0.143935,0.146552,0.149169,0.151786,0.154403,0.15702,0.159637,0.162254,0.164871,0.167488,0.170105,0.172722,0.175339,0.177956,0.180573,0.18319,0.185807,0.188424,0.191041,0.193658,0.196275,0.198892,0.201509,0.204126,0.206743,0.20936,0.211977,0.214594,0.217211,0.219828,0.222445,0.225062,0.227679,0.230296,0.232913,0.23553,0.238147,0.240764,0.243381,0.245998,0.248615,0.251232,0.253849,0.256466,0.259083,0.2617,0.264317,0.266934,0.269551,0.272168,0.274785,0.277402,0.280019,0.282636,0.285253,0.28787,0.290487,0.293104,0.295721,0.298338,0.300955,0.303572,0.306189,0.308806,0.311423,0.31404,0.316657,0.319274,0.321891,0.324508,0.327125,0.329742,0.332359,0.334976,0.337593,0.34021,0.342827,0.345444,0.348061,0.350678,0.353295,0.355912,0.358529,0.361146,0.363763,0.36638,0.368997,0.371614,0.374231,0.376848,0.379465,0.382082,0.384699,0.387316,0.389933,0.39255,0.395167,0.397784,0.400401,0.403018,0.405635,0.408252,0.410869,0.413486,0.416103,0.41872,0.421337,0.423954,0.426571,0.429188,0.431805,0.434422,0.437039,0.439656,0.442273,0.44489,0.447507,0.450124,0.452741,0.455358,0.457975,0.460592,0.463209,0.465826,0.468443,0.47106,0.473677,0.476294,0.478911,0.481528,0.484145,0.486762,0.489379,0.491996,0.494613,0.49723,0.499847,0.502464,0.505081,0.507698,0.510315,0.512932,0.515549,0.518166,0.520783,0.5234,0.526017,0.528634,0.531251,0.533868,0.536485,0.539102,0.541719,0.544336,0.546953,0.54957,0.552187,0.554804,0.557421,0.560038,0.562655,0.565272,0.567889,0.570506,0.573123,0.57574,0.578357,0.580974,0.583591,0.586208,0.588825,0.591442,0.594059,0.596676,0.599293,0.60191,0.604527,0.607144,0.609761,0.612378,0.614995,0.617612,0.620229,0.622846,0.625463,0.62808,0.630697,0.633314,0.635931,0.638548,0.641165,0.643782,0.646399,0.649016,0.651633,0.65425,0.656867,0.659484,0.662101,0.664718,0.667335,0.669952,0.672569,0.675186,0.677803,0.68042,0.683037,0.685654,0.688271,0.690888,0.693505,0.696122,0.698739,0.701356,0.703973,0.70659,0.709207,0.711824,0.714441,0.717058,0.719675,0.722292,0.724909,0.727526,0.730143,0.73276,0.735377,0.737994,0.740611,0.743228,0.745845,0.748462,0.751079,0.753696,0.756313,0.75893,0.761547,0.764164,0.766781,0.769398,0.772015,0.774632,0.777249,0.779866,0.782483,0.7851,0.787717,0.790334,0.792951,0.795568,0.798185,0.800802,0.803419,0.806036,0.808653,0.81127,0.813887,0.816504,0.819121,0.821738,0.824355,0.826972,0.829589,0.832206,0.834823,0.83744,0.840057,0.842674,0.845291,0.847908,0.850525,0.853142,0.855759,0.858376,0.860993,0.86361,0.866227,0.868844,0.871461,0.874078,0.876695,0.879312,0.881929,0.884546,0.887163,0.88978,0.892397,0.895014,0.897631,0.900248,0.902865,0.905482,0.908099,0.910716,0.913333,0.91595,0.918567,0.921184,0.923801,0.926418,0.929035,0.931652,0.934269,0.936886,0.939503,0.94212,0.944737,0.947354,0.949971,0.952588,0.955205,0.957822,0.960439,0.963056,0.965673,0.96829,0.970907,0.973524,0.976141,0.978758,0.981375,0.983992,0.986609,0.989226,0.991843,0.99446,0.997077,0.999694,1.002311],
    "metadata": {
      "title": "Quick Start Example",
      "category": "documentation",
      "created": "2026-01-04"
    }
  }' | jq .

Expected Response

json
{
  "success": true,
  "id": "doc_quickstart_1",
  "message": "Vector inserted into HNSW index"
}
3

Search for similar vectors

Find the k nearest neighbors to a query vector:

bash
curl -s -X POST "https://api.quartzdb.io/api/vector/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "vector": [0,0.002617,0.005234,0.007851,0.010468,0.013085,0.015702,0.018319,0.020936,0.023553,0.02617,0.028787,0.031404,0.034021,0.036638,0.039255,0.041872,0.044489,0.047106,0.049723,0.05234,0.054957,0.057574,0.060191,0.062808,0.065425,0.068042,0.070659,0.073276,0.075893,0.07851,0.081127,0.083744,0.086361,0.088978,0.091595,0.094212,0.096829,0.099446,0.102063,0.10468,0.107297,0.109914,0.112531,0.115148,0.117765,0.120382,0.122999,0.125616,0.128233,0.13085,0.133467,0.136084,0.138701,0.141318,0.143935,0.146552,0.149169,0.151786,0.154403,0.15702,0.159637,0.162254,0.164871,0.167488,0.170105,0.172722,0.175339,0.177956,0.180573,0.18319,0.185807,0.188424,0.191041,0.193658,0.196275,0.198892,0.201509,0.204126,0.206743,0.20936,0.211977,0.214594,0.217211,0.219828,0.222445,0.225062,0.227679,0.230296,0.232913,0.23553,0.238147,0.240764,0.243381,0.245998,0.248615,0.251232,0.253849,0.256466,0.259083,0.2617,0.264317,0.266934,0.269551,0.272168,0.274785,0.277402,0.280019,0.282636,0.285253,0.28787,0.290487,0.293104,0.295721,0.298338,0.300955,0.303572,0.306189,0.308806,0.311423,0.31404,0.316657,0.319274,0.321891,0.324508,0.327125,0.329742,0.332359,0.334976,0.337593,0.34021,0.342827,0.345444,0.348061,0.350678,0.353295,0.355912,0.358529,0.361146,0.363763,0.36638,0.368997,0.371614,0.374231,0.376848,0.379465,0.382082,0.384699,0.387316,0.389933,0.39255,0.395167,0.397784,0.400401,0.403018,0.405635,0.408252,0.410869,0.413486,0.416103,0.41872,0.421337,0.423954,0.426571,0.429188,0.431805,0.434422,0.437039,0.439656,0.442273,0.44489,0.447507,0.450124,0.452741,0.455358,0.457975,0.460592,0.463209,0.465826,0.468443,0.47106,0.473677,0.476294,0.478911,0.481528,0.484145,0.486762,0.489379,0.491996,0.494613,0.49723,0.499847,0.502464,0.505081,0.507698,0.510315,0.512932,0.515549,0.518166,0.520783,0.5234,0.526017,0.528634,0.531251,0.533868,0.536485,0.539102,0.541719,0.544336,0.546953,0.54957,0.552187,0.554804,0.557421,0.560038,0.562655,0.565272,0.567889,0.570506,0.573123,0.57574,0.578357,0.580974,0.583591,0.586208,0.588825,0.591442,0.594059,0.596676,0.599293,0.60191,0.604527,0.607144,0.609761,0.612378,0.614995,0.617612,0.620229,0.622846,0.625463,0.62808,0.630697,0.633314,0.635931,0.638548,0.641165,0.643782,0.646399,0.649016,0.651633,0.65425,0.656867,0.659484,0.662101,0.664718,0.667335,0.669952,0.672569,0.675186,0.677803,0.68042,0.683037,0.685654,0.688271,0.690888,0.693505,0.696122,0.698739,0.701356,0.703973,0.70659,0.709207,0.711824,0.714441,0.717058,0.719675,0.722292,0.724909,0.727526,0.730143,0.73276,0.735377,0.737994,0.740611,0.743228,0.745845,0.748462,0.751079,0.753696,0.756313,0.75893,0.761547,0.764164,0.766781,0.769398,0.772015,0.774632,0.777249,0.779866,0.782483,0.7851,0.787717,0.790334,0.792951,0.795568,0.798185,0.800802,0.803419,0.806036,0.808653,0.81127,0.813887,0.816504,0.819121,0.821738,0.824355,0.826972,0.829589,0.832206,0.834823,0.83744,0.840057,0.842674,0.845291,0.847908,0.850525,0.853142,0.855759,0.858376,0.860993,0.86361,0.866227,0.868844,0.871461,0.874078,0.876695,0.879312,0.881929,0.884546,0.887163,0.88978,0.892397,0.895014,0.897631,0.900248,0.902865,0.905482,0.908099,0.910716,0.913333,0.91595,0.918567,0.921184,0.923801,0.926418,0.929035,0.931652,0.934269,0.936886,0.939503,0.94212,0.944737,0.947354,0.949971,0.952588,0.955205,0.957822,0.960439,0.963056,0.965673,0.96829,0.970907,0.973524,0.976141,0.978758,0.981375,0.983992,0.986609,0.989226,0.991843,0.99446,0.997077,0.999694,1.002311],
    "k": 5
  }' | jq .

Expected Response

json
{
  "success": true,
  "count": 5,
  "algorithm": "HNSW",
  "results": [
    {
      "id": "doc_quickstart_1",
      "score": 1.0,
      "distance": 0.0,
      "metadata": {
        "title": "Quick Start Example",
        "category": "documentation",
        "created": "2026-01-04"
      }
    },
    {
      "id": "doc_similar_1",
      "score": 0.89,
      "distance": 0.11,
      "metadata": {"title": "Another Document"}
    }
  ]
}
Understanding scores: Score of 1.0 = exact match, 0.0 = completely different. Distance is the inverse (0.0 = identical, higher = more different).

Health Check

GET/health

Check if the service is running. No authentication required.

Request

bash
curl -s "https://api.quartzdb.io/health"

Response

json
{
  "status": "healthy",
  "service": "quartz-faas",
  "version": "0.1.0",
  "uptime_seconds": 3600,
  "checks": {
    "storage": "ok",
    "vector_index": "ok"
  }
}

Insert Vector

POST/api/vector/insert🔒 Auth Required

Insert a single vector with optional metadata.

Request Body Parameters

ParameterTypeRequiredDescription
idstring✓Unique identifier (1-256 chars, alphanumeric, dash, underscore)
vectornumber[]✓Array of exactly 384 floating-point numbers
metadataobject-Optional JSON object with custom data

Request Example

bash
curl -s -X POST "https://api.quartzdb.io/api/vector/insert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "id": "product_12345",
    "vector": [0,0.002617,0.005234,0.007851,0.010468,0.013085,0.015702,0.018319,0.020936,0.023553,0.02617,0.028787,0.031404,0.034021,0.036638,0.039255,0.041872,0.044489,0.047106,0.049723,0.05234,0.054957,0.057574,0.060191,0.062808,0.065425,0.068042,0.070659,0.073276,0.075893,0.07851,0.081127,0.083744,0.086361,0.088978,0.091595,0.094212,0.096829,0.099446,0.102063,0.10468,0.107297,0.109914,0.112531,0.115148,0.117765,0.120382,0.122999,0.125616,0.128233,0.13085,0.133467,0.136084,0.138701,0.141318,0.143935,0.146552,0.149169,0.151786,0.154403,0.15702,0.159637,0.162254,0.164871,0.167488,0.170105,0.172722,0.175339,0.177956,0.180573,0.18319,0.185807,0.188424,0.191041,0.193658,0.196275,0.198892,0.201509,0.204126,0.206743,0.20936,0.211977,0.214594,0.217211,0.219828,0.222445,0.225062,0.227679,0.230296,0.232913,0.23553,0.238147,0.240764,0.243381,0.245998,0.248615,0.251232,0.253849,0.256466,0.259083,0.2617,0.264317,0.266934,0.269551,0.272168,0.274785,0.277402,0.280019,0.282636,0.285253,0.28787,0.290487,0.293104,0.295721,0.298338,0.300955,0.303572,0.306189,0.308806,0.311423,0.31404,0.316657,0.319274,0.321891,0.324508,0.327125,0.329742,0.332359,0.334976,0.337593,0.34021,0.342827,0.345444,0.348061,0.350678,0.353295,0.355912,0.358529,0.361146,0.363763,0.36638,0.368997,0.371614,0.374231,0.376848,0.379465,0.382082,0.384699,0.387316,0.389933,0.39255,0.395167,0.397784,0.400401,0.403018,0.405635,0.408252,0.410869,0.413486,0.416103,0.41872,0.421337,0.423954,0.426571,0.429188,0.431805,0.434422,0.437039,0.439656,0.442273,0.44489,0.447507,0.450124,0.452741,0.455358,0.457975,0.460592,0.463209,0.465826,0.468443,0.47106,0.473677,0.476294,0.478911,0.481528,0.484145,0.486762,0.489379,0.491996,0.494613,0.49723,0.499847,0.502464,0.505081,0.507698,0.510315,0.512932,0.515549,0.518166,0.520783,0.5234,0.526017,0.528634,0.531251,0.533868,0.536485,0.539102,0.541719,0.544336,0.546953,0.54957,0.552187,0.554804,0.557421,0.560038,0.562655,0.565272,0.567889,0.570506,0.573123,0.57574,0.578357,0.580974,0.583591,0.586208,0.588825,0.591442,0.594059,0.596676,0.599293,0.60191,0.604527,0.607144,0.609761,0.612378,0.614995,0.617612,0.620229,0.622846,0.625463,0.62808,0.630697,0.633314,0.635931,0.638548,0.641165,0.643782,0.646399,0.649016,0.651633,0.65425,0.656867,0.659484,0.662101,0.664718,0.667335,0.669952,0.672569,0.675186,0.677803,0.68042,0.683037,0.685654,0.688271,0.690888,0.693505,0.696122,0.698739,0.701356,0.703973,0.70659,0.709207,0.711824,0.714441,0.717058,0.719675,0.722292,0.724909,0.727526,0.730143,0.73276,0.735377,0.737994,0.740611,0.743228,0.745845,0.748462,0.751079,0.753696,0.756313,0.75893,0.761547,0.764164,0.766781,0.769398,0.772015,0.774632,0.777249,0.779866,0.782483,0.7851,0.787717,0.790334,0.792951,0.795568,0.798185,0.800802,0.803419,0.806036,0.808653,0.81127,0.813887,0.816504,0.819121,0.821738,0.824355,0.826972,0.829589,0.832206,0.834823,0.83744,0.840057,0.842674,0.845291,0.847908,0.850525,0.853142,0.855759,0.858376,0.860993,0.86361,0.866227,0.868844,0.871461,0.874078,0.876695,0.879312,0.881929,0.884546,0.887163,0.88978,0.892397,0.895014,0.897631,0.900248,0.902865,0.905482,0.908099,0.910716,0.913333,0.91595,0.918567,0.921184,0.923801,0.926418,0.929035,0.931652,0.934269,0.936886,0.939503,0.94212,0.944737,0.947354,0.949971,0.952588,0.955205,0.957822,0.960439,0.963056,0.965673,0.96829,0.970907,0.973524,0.976141,0.978758,0.981375,0.983992,0.986609,0.989226,0.991843,0.99446,0.997077,0.999694,1.002311],
    "metadata": {
      "name": "Wireless Headphones",
      "price": 79.99,
      "category": "electronics",
      "tags": ["audio", "bluetooth", "wireless"]
    }
  }' | jq .

Success Response

json
{
  "success": true,
  "id": "product_12345",
  "message": "Vector inserted into HNSW index"
}

Error Response (duplicate ID)

json
{
  "success": false,
  "error": "Vector with ID 'product_12345' already exists"
}

Batch Insert

POST/api/vector/batch-insert🔒 Auth Required

Insert multiple vectors in a single request. Maximum 100 vectors per batch.

Request Body Parameters

ParameterTypeRequiredDescription
vectorsarray✓Array of vector objects (max 100). Each must have id, vector, and optional metadata.

Request Example

bash
curl -s -X POST "https://api.quartzdb.io/api/vector/batch-insert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "vectors": [
      {
        "id": "batch_item_1",
        "vector": [0,0.002617,0.005234,0.007851,0.010468,0.013085,0.015702,0.018319,0.020936,0.023553,0.02617,0.028787,0.031404,0.034021,0.036638,0.039255,0.041872,0.044489,0.047106,0.049723,0.05234,0.054957,0.057574,0.060191,0.062808,0.065425,0.068042,0.070659,0.073276,0.075893,0.07851,0.081127,0.083744,0.086361,0.088978,0.091595,0.094212,0.096829,0.099446,0.102063,0.10468,0.107297,0.109914,0.112531,0.115148,0.117765,0.120382,0.122999,0.125616,0.128233,0.13085,0.133467,0.136084,0.138701,0.141318,0.143935,0.146552,0.149169,0.151786,0.154403,0.15702,0.159637,0.162254,0.164871,0.167488,0.170105,0.172722,0.175339,0.177956,0.180573,0.18319,0.185807,0.188424,0.191041,0.193658,0.196275,0.198892,0.201509,0.204126,0.206743,0.20936,0.211977,0.214594,0.217211,0.219828,0.222445,0.225062,0.227679,0.230296,0.232913,0.23553,0.238147,0.240764,0.243381,0.245998,0.248615,0.251232,0.253849,0.256466,0.259083,0.2617,0.264317,0.266934,0.269551,0.272168,0.274785,0.277402,0.280019,0.282636,0.285253,0.28787,0.290487,0.293104,0.295721,0.298338,0.300955,0.303572,0.306189,0.308806,0.311423,0.31404,0.316657,0.319274,0.321891,0.324508,0.327125,0.329742,0.332359,0.334976,0.337593,0.34021,0.342827,0.345444,0.348061,0.350678,0.353295,0.355912,0.358529,0.361146,0.363763,0.36638,0.368997,0.371614,0.374231,0.376848,0.379465,0.382082,0.384699,0.387316,0.389933,0.39255,0.395167,0.397784,0.400401,0.403018,0.405635,0.408252,0.410869,0.413486,0.416103,0.41872,0.421337,0.423954,0.426571,0.429188,0.431805,0.434422,0.437039,0.439656,0.442273,0.44489,0.447507,0.450124,0.452741,0.455358,0.457975,0.460592,0.463209,0.465826,0.468443,0.47106,0.473677,0.476294,0.478911,0.481528,0.484145,0.486762,0.489379,0.491996,0.494613,0.49723,0.499847,0.502464,0.505081,0.507698,0.510315,0.512932,0.515549,0.518166,0.520783,0.5234,0.526017,0.528634,0.531251,0.533868,0.536485,0.539102,0.541719,0.544336,0.546953,0.54957,0.552187,0.554804,0.557421,0.560038,0.562655,0.565272,0.567889,0.570506,0.573123,0.57574,0.578357,0.580974,0.583591,0.586208,0.588825,0.591442,0.594059,0.596676,0.599293,0.60191,0.604527,0.607144,0.609761,0.612378,0.614995,0.617612,0.620229,0.622846,0.625463,0.62808,0.630697,0.633314,0.635931,0.638548,0.641165,0.643782,0.646399,0.649016,0.651633,0.65425,0.656867,0.659484,0.662101,0.664718,0.667335,0.669952,0.672569,0.675186,0.677803,0.68042,0.683037,0.685654,0.688271,0.690888,0.693505,0.696122,0.698739,0.701356,0.703973,0.70659,0.709207,0.711824,0.714441,0.717058,0.719675,0.722292,0.724909,0.727526,0.730143,0.73276,0.735377,0.737994,0.740611,0.743228,0.745845,0.748462,0.751079,0.753696,0.756313,0.75893,0.761547,0.764164,0.766781,0.769398,0.772015,0.774632,0.777249,0.779866,0.782483,0.7851,0.787717,0.790334,0.792951,0.795568,0.798185,0.800802,0.803419,0.806036,0.808653,0.81127,0.813887,0.816504,0.819121,0.821738,0.824355,0.826972,0.829589,0.832206,0.834823,0.83744,0.840057,0.842674,0.845291,0.847908,0.850525,0.853142,0.855759,0.858376,0.860993,0.86361,0.866227,0.868844,0.871461,0.874078,0.876695,0.879312,0.881929,0.884546,0.887163,0.88978,0.892397,0.895014,0.897631,0.900248,0.902865,0.905482,0.908099,0.910716,0.913333,0.91595,0.918567,0.921184,0.923801,0.926418,0.929035,0.931652,0.934269,0.936886,0.939503,0.94212,0.944737,0.947354,0.949971,0.952588,0.955205,0.957822,0.960439,0.963056,0.965673,0.96829,0.970907,0.973524,0.976141,0.978758,0.981375,0.983992,0.986609,0.989226,0.991843,0.99446,0.997077,0.999694,1.002311],
        "metadata": {"index": 1}
      },
      {
        "id": "batch_item_2",
        "vector": [0,0.002617,0.005234,0.007851,0.010468,0.013085,0.015702,0.018319,0.020936,0.023553,0.02617,0.028787,0.031404,0.034021,0.036638,0.039255,0.041872,0.044489,0.047106,0.049723,0.05234,0.054957,0.057574,0.060191,0.062808,0.065425,0.068042,0.070659,0.073276,0.075893,0.07851,0.081127,0.083744,0.086361,0.088978,0.091595,0.094212,0.096829,0.099446,0.102063,0.10468,0.107297,0.109914,0.112531,0.115148,0.117765,0.120382,0.122999,0.125616,0.128233,0.13085,0.133467,0.136084,0.138701,0.141318,0.143935,0.146552,0.149169,0.151786,0.154403,0.15702,0.159637,0.162254,0.164871,0.167488,0.170105,0.172722,0.175339,0.177956,0.180573,0.18319,0.185807,0.188424,0.191041,0.193658,0.196275,0.198892,0.201509,0.204126,0.206743,0.20936,0.211977,0.214594,0.217211,0.219828,0.222445,0.225062,0.227679,0.230296,0.232913,0.23553,0.238147,0.240764,0.243381,0.245998,0.248615,0.251232,0.253849,0.256466,0.259083,0.2617,0.264317,0.266934,0.269551,0.272168,0.274785,0.277402,0.280019,0.282636,0.285253,0.28787,0.290487,0.293104,0.295721,0.298338,0.300955,0.303572,0.306189,0.308806,0.311423,0.31404,0.316657,0.319274,0.321891,0.324508,0.327125,0.329742,0.332359,0.334976,0.337593,0.34021,0.342827,0.345444,0.348061,0.350678,0.353295,0.355912,0.358529,0.361146,0.363763,0.36638,0.368997,0.371614,0.374231,0.376848,0.379465,0.382082,0.384699,0.387316,0.389933,0.39255,0.395167,0.397784,0.400401,0.403018,0.405635,0.408252,0.410869,0.413486,0.416103,0.41872,0.421337,0.423954,0.426571,0.429188,0.431805,0.434422,0.437039,0.439656,0.442273,0.44489,0.447507,0.450124,0.452741,0.455358,0.457975,0.460592,0.463209,0.465826,0.468443,0.47106,0.473677,0.476294,0.478911,0.481528,0.484145,0.486762,0.489379,0.491996,0.494613,0.49723,0.499847,0.502464,0.505081,0.507698,0.510315,0.512932,0.515549,0.518166,0.520783,0.5234,0.526017,0.528634,0.531251,0.533868,0.536485,0.539102,0.541719,0.544336,0.546953,0.54957,0.552187,0.554804,0.557421,0.560038,0.562655,0.565272,0.567889,0.570506,0.573123,0.57574,0.578357,0.580974,0.583591,0.586208,0.588825,0.591442,0.594059,0.596676,0.599293,0.60191,0.604527,0.607144,0.609761,0.612378,0.614995,0.617612,0.620229,0.622846,0.625463,0.62808,0.630697,0.633314,0.635931,0.638548,0.641165,0.643782,0.646399,0.649016,0.651633,0.65425,0.656867,0.659484,0.662101,0.664718,0.667335,0.669952,0.672569,0.675186,0.677803,0.68042,0.683037,0.685654,0.688271,0.690888,0.693505,0.696122,0.698739,0.701356,0.703973,0.70659,0.709207,0.711824,0.714441,0.717058,0.719675,0.722292,0.724909,0.727526,0.730143,0.73276,0.735377,0.737994,0.740611,0.743228,0.745845,0.748462,0.751079,0.753696,0.756313,0.75893,0.761547,0.764164,0.766781,0.769398,0.772015,0.774632,0.777249,0.779866,0.782483,0.7851,0.787717,0.790334,0.792951,0.795568,0.798185,0.800802,0.803419,0.806036,0.808653,0.81127,0.813887,0.816504,0.819121,0.821738,0.824355,0.826972,0.829589,0.832206,0.834823,0.83744,0.840057,0.842674,0.845291,0.847908,0.850525,0.853142,0.855759,0.858376,0.860993,0.86361,0.866227,0.868844,0.871461,0.874078,0.876695,0.879312,0.881929,0.884546,0.887163,0.88978,0.892397,0.895014,0.897631,0.900248,0.902865,0.905482,0.908099,0.910716,0.913333,0.91595,0.918567,0.921184,0.923801,0.926418,0.929035,0.931652,0.934269,0.936886,0.939503,0.94212,0.944737,0.947354,0.949971,0.952588,0.955205,0.957822,0.960439,0.963056,0.965673,0.96829,0.970907,0.973524,0.976141,0.978758,0.981375,0.983992,0.986609,0.989226,0.991843,0.99446,0.997077,0.999694,1.002311],
        "metadata": {"index": 2}
      }
    ]
  }' | jq .

Success Response

json
{
  "success": true,
  "total": 2,
  "inserted": 2,
  "failed": 0,
  "results": [
    {"id": "batch_item_1", "success": true, "message": "inserted"},
    {"id": "batch_item_2", "success": true, "message": "inserted"}
  ]
}

Get Vector by ID

GET/api/vector/get/:id🔒 Auth Required

Retrieve a specific vector and its metadata by ID.

URL Parameters

ParameterTypeRequiredDescription
idstring✓The ID of the vector to retrieve

Request Example

bash
curl -s "https://api.quartzdb.io/api/vector/get/product_12345" \
  -H "X-API-Key: $API_KEY" | jq .

Success Response

json
{
  "id": "product_12345",
  "vector": [0.0, 0.002617, 0.005234, ...],
  "metadata": {
    "name": "Wireless Headphones",
    "price": 79.99
  }
}

Error Response (not found)

text
Vector 'nonexistent_id' not found

Delete Vector

DELETE/api/vector/delete🔒 Auth Required

Soft-delete a vector by ID. The vector is marked as deleted but storage is reclaimed during compaction.

Request Body Parameters

ParameterTypeRequiredDescription
idstring✓ID of the vector to delete

Request Example

bash
curl -s -X DELETE "https://api.quartzdb.io/api/vector/delete" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"id": "product_12345"}' | jq .

Success Response

json
{
  "success": true,
  "message": "Vector deleted"
}

Statistics

GET/api/vector/stats🔒 Auth Required

Get index statistics and health information.

Request Example

bash
curl -s "https://api.quartzdb.io/api/vector/stats" \
  -H "X-API-Key: $API_KEY" | jq .

Response

json
{
  "success": true,
  "algorithm": "HNSW",
  "dimension": 384,
  "num_vectors": 1000,
  "num_active": 950,
  "num_deleted": 50,
  "num_nodes": 950,
  "entry_point_level": 3,
  "connections_per_layer": [0, 12, 156, 782],
  "deletion_ratio_percent": "5.0",
  "recommendation": "Healthy: <10% vectors deleted"
}

Response Fields

ParameterTypeRequiredDescription
dimensionnumber✓Vector dimensions (always 384)
num_vectorsnumber✓Total vectors (active + deleted)
num_activenumber✓Active (non-deleted) vectors
num_deletednumber✓Soft-deleted vectors
deletion_ratio_percentstring✓Percentage of deleted vectors
recommendationstring✓Health recommendation

Creating Embeddings

Important: QuartzDB stores vectors - it does NOT generate embeddings. You must use an external embedding model to convert text/images into 384-dimensional vectors.

What are Embeddings?

Embeddings are numerical representations of data (text, images, audio) that capture semantic meaning. Similar items have similar embeddings, enabling semantic search.

Recommended Models (384 dimensions)

ModelBest ForSpeed
all-MiniLM-L6-v2General semantic searchFast
paraphrase-MiniLM-L6-v2Paraphrase detectionFast
multi-qa-MiniLM-L6-cos-v1Question answeringFast

Python Example (Complete)

Install dependencies first: pip install sentence-transformers requests

python
#!/usr/bin/env python3
"""
QuartzDB Python Example - Complete working code
Requires: pip install sentence-transformers requests
"""

from sentence_transformers import SentenceTransformer
import requests
import json

# Configuration
API_URL = "https://api.quartzdb.io"
API_KEY = "YOUR_API_KEY"  # Replace with your actual API key

# Load the embedding model (downloads on first run, ~90MB)
print("Loading embedding model...")
model = SentenceTransformer('all-MiniLM-L6-v2')

# Sample documents to index
documents = [
    {"id": "doc_1", "text": "Python is a programming language", "category": "tech"},
    {"id": "doc_2", "text": "Machine learning enables computers to learn", "category": "ai"},
    {"id": "doc_3", "text": "Vector databases store embeddings", "category": "database"},
]

# Insert documents
print("\nInserting documents...")
for doc in documents:
    # Generate embedding (returns 384-dimensional vector)
    vector = model.encode(doc["text"]).tolist()
    
    # Insert into QuartzDB
    response = requests.post(
        f"{API_URL}/api/vector/insert",
        headers={
            "Content-Type": "application/json",
            "X-API-Key": API_KEY
        },
        json={
            "id": doc["id"],
            "vector": vector,
            "metadata": {
                "text": doc["text"],
                "category": doc["category"]
            }
        }
    )
    print(f"  {doc['id']}: {response.json()}")

# Search for similar documents
query = "What is artificial intelligence?"
print(f"\nSearching for: '{query}'")

query_vector = model.encode(query).tolist()

response = requests.post(
    f"{API_URL}/api/vector/search",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
    },
    json={
        "vector": query_vector,
        "k": 3
    }
)

results = response.json()
print(f"\nTop {len(results['results'])} results:")
for i, result in enumerate(results['results'], 1):
    print(f"  {i}. {result['id']} (score: {result['score']:.3f})")
    if result.get('metadata'):
        print(f"     Text: {result['metadata'].get('text', 'N/A')}")

JavaScript/Node.js Example

For Node.js, use the @xenova/transformers package:

javascript
// npm install @xenova/transformers

import { pipeline } from '@xenova/transformers';

const API_URL = 'https://api.quartzdb.io';
const API_KEY = 'YOUR_API_KEY';

// Load the embedding model
const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');

// Generate embedding for text
async function getEmbedding(text) {
  const output = await embedder(text, { pooling: 'mean', normalize: true });
  return Array.from(output.data);
}

// Insert a document
async function insertDocument(id, text, metadata = {}) {
  const vector = await getEmbedding(text);
  
  const response = await fetch(`${API_URL}/api/vector/insert`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ id, vector, metadata: { ...metadata, text } })
  });
  
  return response.json();
}

// Search for similar documents
async function search(query, k = 10) {
  const vector = await getEmbedding(query);
  
  const response = await fetch(`${API_URL}/api/vector/search`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({ vector, k })
  });
  
  return response.json();
}

// Example usage
await insertDocument('doc_1', 'QuartzDB is a vector database');
const results = await search('What is QuartzDB?');
console.log(results);

Best Practices

Use batch insert for bulk data
When inserting many vectors, use /api/vector/batch-insert with up to 100 vectors per request. This is much faster than individual inserts.
Normalize your vectors
For best cosine similarity results, normalize vectors to unit length. Most embedding models do this automatically.
Store useful metadata
Include metadata like text snippets, IDs, URLs, or categories to make search results actionable without additional lookups.
Use meaningful IDs
Use descriptive IDs like 'product_12345' or 'doc_article_slug' instead of random UUIDs for easier debugging.
Monitor deletion ratio
Check /api/vector/stats regularly. If deletion_ratio_percent exceeds 20%, index performance may degrade.
Handle errors gracefully
Always check response success field and handle HTTP error codes (401 unauthorized, 400 bad request, 429 rate limited).