Skip to main content

​
CollectionsClient

Client for managing collections. This client provides methods to create, list, get, and delete collections. Get an instance of CollectionsClient by calling client.collections(): 
import { Client } from "topk-js";

const client = new Client({
  apiKey: "YOUR_TOPK_API_KEY",
  region: "aws-us-east-1-elastica"
});

const collectionsClient = client.collections();

​
Methods

​
list()

Lists all collections in the current project. 
const collections = await client.collections().list();

collections.forEach(collection => {
  console.log(`Collection: ${collection.name}`);
  console.log(`Region: ${collection.region}`);
  console.log(`Schema:`, collection.schema);
});
​
return
Promise<Array<Collection>>
A promise that resolves to an array of Collection objects

​
create(name, schema)

Creates a new collection with the specified schema.
​
name
string
required
Name of the collection to create
​
schema
Record<string, schema.FieldSpec>
required
Schema definition for the collection fields
import { text, int, semanticIndex } from "topk-js/schema";

const collection = await client.collections().create("books", {
  title: text().required().index(semanticIndex()),
  author: text(),
  published_year: int()
});
​
return
Promise<Collection>
A promise that resolves to the created Collection object

​
get(name)

Retrieves information about a specific collection.
​
name
string
required
Name of the collection to retrieve
const collection = await client.collections().get("books");

console.log(`Collection: ${collection.name}`);
console.log(`Organization ID: ${collection.orgId}`);
console.log(`Project ID: ${collection.projectId}`);
console.log(`Region: ${collection.region}`);
console.log(`Schema:`, collection.schema);
​
return
Promise<Collection>
A promise that resolves to the Collection object

​
delete(name)

Deletes a collection and all its data.
This operation is irreversible and will permanently delete all data in the collection.
​
name
string
required
Name of the collection to delete
await client.collections().delete("books");
console.log("Collection deleted successfully");
​
return
Promise<void>
A promise that resolves when the collection is deleted

​
Collection

Represents a collection in the TopK service. A collection is a container for documents with a defined schema.
​
name
string
Name of the collection
​
orgId
string
Organization ID that owns the collection
​
projectId
string
Project ID that contains the collection
​
schema
Record<string, CollectionFieldSpec>
Schema definition for the collection fields
​
region
string
Region where the collection is stored

​
CollectionFieldSpec

Represents a field specification within a collection schema. This struct defines the properties of a field in a collection, including its data type, whether it’s required, and any index configuration.
​
dataType
schema.DataType
Data type of the field
​
required
boolean
Whether the field is required (must be present in all documents)
​
index
schema.FieldIndexUnion
Index configuration for the field (optional)

​
Example: Complete Workflow

import { Client } from "topk-js";
import { text, int, semanticIndex, keywordIndex } from "topk-js/schema";
import { select, field, fn } from "topk-js/query";

const client = new Client({
  apiKey: "YOUR_TOPK_API_KEY",
  region: "aws-us-east-1-elastica"
});

// Create a collection
await client.collections().create("books", {
  title: text().required().index(semanticIndex()),
  author: text().index(keywordIndex()),
  published_year: int()
});

// List all collections
const collections = await client.collections().list();
console.log(`Total collections: ${collections.length}`);

// Get collection details
const booksCollection = await client.collections().get("books");
console.log(`Books collection schema:`, booksCollection.schema);

// Add documents to the collection
await client.collection("books").upsert([
  { 
    _id: "gatsby", 
    title: "The Great Gatsby", 
    author: "F. Scott Fitzgerald",
    published_year: 1925
  },
  { 
    _id: "1984", 
    title: "1984", 
    author: "George Orwell",
    published_year: 1949
  }
]);

// Query the collection
const results = await client.collection("books").query(
  select({
    title: field("title"),
    author: field("author"),
    similarity: fn.semanticSimilarity("title", "dystopian future")
  })
  .topk(field("similarity"), 10)
);

console.log("Search results:", results);

// Delete the collection (use with caution!)
await client.collections().delete("books");

Build docs developers (and LLMs) love

Get started for freeTalk to us