Whatever message this page gives is out now! Go check it out!
Connect to hosted vector databases and tune ingest
Last update:
May 18, 2026
Learn how to connect ColdFusion to hosted vector databases (Milvus, Pinecone, Qdrant, Chroma), align embedding dimensions, and tune ingest with chunking, batching, timeouts, and retries for production-ready RAG.
Introduction
Hosted or self-managed vector databases persist data across restarts, scale with your cluster, and support production SLAs. ColdFusion uses a single struct shape for vectorStore({ ... }): set provider, endpoint fields, dimension, and optional embeddingModel, connectionSettings, and retrySettings.
Topic | You will |
Inline hosted config | Build a struct for Milvus, Pinecone, Qdrant, or Chroma and call vectorStore(config). |
Embedding in the store | Add embeddingModel so add and search accept text only. |
Collections and partitions | Set collectionName, databaseName, namespace, tenantName, or index blocks (Pinecone serverless vs pod) per provider. |
Tune ingest | Chunk content, call addAll in batches, and adjust timeouts and retries for large loads. |
Note: dimension on the store must match the output size of the embedding model you attach. A mismatch raises a dimension error at runtime.
Pre-requisites
- ColdFusion 2025.0.08
- A running Milvus, Pinecone, Qdrant, or Chroma deployment (or cloud account) and credentials
- Network path from the ColdFusion server to the provider endpoint
List of supported providers
Provider | Typical connection | Highlights |
Milvus | url (gRPC), dimension, optional collectionName, databaseName | Rich index options (metricType, indexType); connectionSettings / retrySettings. |
Pinecone | apiKey, indexName, namespace | Requires either a serverless block or a pod block (not both); all fields inside the chosen block are required. |
Qdrant | url, dimension | Optional apiKey, collectionName; connectionSettings / retrySettings. |
Chroma | url | collectionName, databaseName, tenantName for multi-tenant setups; top-level callTimeout. |
Embedding models: concepts and configuration
An embedding model turns text into a vector (a fixed-length array of numbers). Similar meanings produce vectors that are closer in the space your vector database searches. The vector store does not invent that mapping—you either:
- Attach an embeddingModel to vectorStore({ ... }) so add and search call the model for you when you pass text, or
- Call embeddingModel(embeddingConfig) yourself and use embed / embedAll when you build vectors outside the normal add path (ETL, experiments, or passing vector on each row).
embeddingModel struct fields
Use the same struct shape inside vectorStore({ embeddingModel: { ... } }) or when you call embeddingModel(embeddingConfig) standalone.
Field | Required | Default | Description |
provider | Yes | — | Provider id, for example openai, azureopenai, mistral, ollama. |
modelName | Yes | — | Model identifier (for example text-embedding-3-small, nomic-embed-text:latest). |
apiKey | Yes* | — | API key where the provider requires it (often not used for local Ollama). |
dimension | Yes | — | Output vector length; must match the vector store dimension and any index dimension (for example Pinecone serverless / pod). |
baseUrl | No | — | Required for Ollama (for example http://localhost:11434). Optional overrides for some cloud APIs. |
maxRetries | No | 3 | Retries for transient embedding API failures. |
timeout | No | 60000 | Timeout in milliseconds for embedding calls. |
logRequests | No | false | Log outbound embedding requests (debugging). |
logResponses | No | false | Log embedding responses (debugging). |
*Some providers (for example, local Ollama) may not require apiKey. See your provider’s documentation.
Note: Numeric timeout values are often in milliseconds; vector store connectionSettings may use seconds for callTimeout.
Dimension alignment
Misaligned dimensions are a common failure:
- Set dimension on the vector store to the embedding model’s output size (for example, 1536 for text-embedding-3-small, 768 for many nomic / Ollama models).
- For Pinecone, the serverless or pod block also carries a **dimension**—it must match.
- If a collection or index already exists with another size, you must use that model, recreate the collection with a new dimension, or use a different collection name.
OpenAI-style cloud models
Pass apiKey, modelName, and dimension that match the model’s documented output size. Example models: text-embedding-3-small (often 1536 dimensions), text-embedding-3-large (often 3072). Always verify in the provider’s current documentation.
Standalone embeddingModel() vs embedding on the store
Approach | When to use it |
embeddingModel nested in vectorStore({ ... }) | Normal add / search with text; simplest production path. |
embeddingModel() + embed / embedAll | Custom pipelines, offline batch files, or when you build vector arrays yourself and pass them into add. |
You can reuse one embeddingConfig struct in both places (for example application.embeddingModel) so dimensions and credentials stay consistent.
Security and credentials
Store API keys in environment variables, secure vaults, or ColdFusion Administrator / encrypted settings, not in source control. Rotate keys if they leak. Restrict network access so that only your ColdFusion host can reach Ollama or cloud-embedding endpoints, if required.
Milvus: inline configuration and embedding
Mandatory fields usually include url and dimension. Set collectionName and databaseName to match how you organize data in Milvus. Attach embeddingModel so text is embedded on add/search.
<cfscript>
try {
vectorstoreclient = vectorStore({
"provider": "milvus",
"url": "http://your-milvus-host:19530",
"databaseName": "default",
"collectionName": "cf_docs",
"dimension": 768,
"metricType": "COSINE",
"indexType": "HNSW",
"apiKey": "",
"embeddingModel": {
"provider": "ollama",
"modelName": "nomic-embed-text:latest",
"baseUrl": "http://localhost:11434",
"dimension": 768
}
});
writeDump(vectorstoreclient.add({
"text": "ColdFusion is a rapid application development platform.",
"metadata": { "product": "coldfusion", "year": 2025 }
}));
writeDump(vectorstoreclient.search({
"text": "rapid application development",
"minScore": 0.25,
"topK": 5,
"filter": { "year": 2025 }
}));
}
catch (any e) {
writeDump(e);
}
</cfscript>Connection and retry tuning (Milvus)
Use connectionSettings for call and idle timeouts, and retrySettings for backoff when the network is flaky.
<cfscript>
vectorstoreclient = vectorStore({
"provider": "milvus",
"url": "http://your-milvus-host:19530",
"dimension": 768,
"collectionName": "cf_docs",
"embeddingModel": { /* ... same dimension ... */ },
"connectionSettings": {
"callTimeout": 60,
"connectionTimeout": 20,
"keepAlive": true,
"idleTimeout": 600
},
"retrySettings": {
"maxRetries": 10,
"initialBackoff": 500,
"maxBackoff": 3000,
"backoffMultiplier": 3
}
});
</cfscript>Pinecone: serverless or pod
You must supply either a serverless or a pod block—not both. apiKey and indexName are typically required. namespace partitions data inside the index.
Serverless (illustrative):
config = {
"provider": "pinecone",
"apiKey": "your-api-key",
"indexName": "my-index",
"namespace": "default",
"serverless": {
"dimension": 128,
"cloud": "aws",
"region": "us-east-1",
"deletionProtection": "disabled"
},
"embeddingModel": {
"provider": "openai",
"modelName": "text-embedding-3-small",
"apiKey": "your-openai-key",
"dimension": 1536
}
};
vectorstoreclient = vectorStore(config); Pod (illustrative):
config = {
"provider": "pinecone",
"apiKey": "your-api-key",
"indexName": "my-pod-index",
"namespace": "default",
"pod": {
"dimension": 128,
"environment": "your-environment",
"podType": "your-pod-type"
}
};
vectorstoreclient = vectorStore(config); Qdrant
url and dimension are typically required. Optional collectionName, apiKey, metricType, plus connectionSettings and retrySettings for tuning.
<cfscript>
try {
vectorstoreclient = vectorStore({
"provider": "qdrant",
"url": "https://your-qdrant.example:6334",
"dimension": 384,
"collectionName": "app_collection",
"metricType": "COSINE",
"embeddingModel": {
"provider": "ollama",
"modelName": "all-minilm:latest",
"baseUrl": "http://localhost:11434",
"dimension": 384
}
});
writeDump(vectorstoreclient.addAll([
{ "text": "First chunk", "metadata": { "doc": "1" } },
{ "text": "Second chunk", "metadata": { "doc": "1" } }
]));
} catch (any e) {
writeDump(e);
}
</cfscript>Chroma
url is required. Set collectionName, databaseName, and tenantName to match your Chroma deployment. callTimeout may appear at the top level of the struct (not nested under connectionSettings).
<cfscript>
try {
vectorstoreclient = vectorStore({
"provider": "chroma",
"url": "http://your-chroma-host:8000",
"collectionName": "kb",
"databaseName": "default",
"tenantName": "default",
"callTimeout": 60,
"embeddingModel": {
"provider": "openai",
"modelName": "text-embedding-3-small",
"apiKey": "your-openai-key",
"dimension": 1536
}
});
writeDump(vectorstoreclient.add({
"text": "Sample for Chroma collection.",
"metadata": { "source": "demo" }
}));
} catch (any e) {
writeDump(e);
}
</cfscript>Attach an embedding model to the vector store
To avoid passing raw vectors on every add, put an embeddingModel struct on the same config you pass to vectorStore(). The model’s output dimension must equal the vector store’s dimension (and Pinecone’s serverless / pod dimension).
You can also assign a shared struct from application.embeddingModel (or a variable built once at startup) if your team centralizes credentials.
vsConfig = {
"provider": "milvus",
"url": "http://my-host:19530",
"databaseName": "default",
"collectionName": "qatest_milvus",
"dimension": 768,
"indexType": "HNSW",
"metricType": "COSINE",
"embeddingModel": application.embeddingModel
};
vectorstoreclient = vectorStore(vsConfig);If you do not attach an embedding model, you must pass vector (or embedding per your API reference) on each add for rows that need vectors.
Precomputed vectors on add: If you use embeddingModel() to call embed yourself, pass the returned vector in the vector field on add (or the field name your API uses), and keep dimension consistent with the store.
Manage collections, databases, and namespaces
- Milvus: databaseName and collectionName select where vectors live. Collections may be created automatically if missing (confirm in your release notes).
- Pinecone: indexName and namespace scope reads and writes.
- Qdrant: collectionName identifies the collection.
- Chroma : databaseName and tenantName matter for multi-tenant Chroma setups.
Tune ingest: chunking and limits
Large pages or imports should be split into chunks (by paragraph, size, or a dedicated splitter). Each chunk becomes one add or addAll row.
Network: Increase callTimeout in connectionSettings for long-running bulk operations. Use retries for transient failures, not for logic errors.
<cfscript>
try {
vectorstoreclient = vectorStore({
"provider": "milvus",
"url": "http://your-milvus-host:19530",
"collectionName": "longform_docs",
"dimension": 1536,
"metricType": "COSINE",
"indexType": "IVF_FLAT",
"embeddingModel": {
"provider": "openai",
"modelName": "text-embedding-3-small",
"apiKey": "add-your-openai-key",
"dimension": 1536
},
"connectionSettings": {
"callTimeout": 120,
"connectionTimeout": 30
}
});
chunks = [];
for (i = 1; i <= 20; i++) {
arrayAppend(chunks, {
"text": "Section " & i & " of the manual. Replace with real chunk text.",
"metadata": { "documentId": "manual-2026", "chunkIndex": i }
});
}
writeDump(vectorstoreclient.addAll(chunks));
} catch (any e) {
writeDump(e);
}
</cfscript>
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
