SingleStore Client

The SingleStore Client is a package designed for interacting with the SingleStore API in Node.js environments.

Installation

``bash
npm install @singlestore/client
`

Example Apps

- Next.js AI Notes App
- Terminal Usage Example

Usage

$3

The SingleStoreClient can be initialized in multiple ways, depending on your needs. Below are examples of how to initialize the client in various scenarios.

#### Default

Use this method if you don’t need Management API access or AI integration.

`ts
import { SingleStoreClient } from "@singlestore/client";

const client = new SingleStoreClient();
`

#### With Management API Access

This method is used when you need to access SingleStore's management API.

`ts
import { SingleStoreClient } from "@singlestore/client";

const client = new SingleStoreClient({ apiKey: "" });
`

#### With AI Functionality

If you want to integrate AI features, use this method. You need to pass an AI instance with the required API key.

`bash
npm install @singlestore/ai
`

`ts
import { AI } from "@singlestore/ai";
import { SingleStoreClient } from "@singlestore/client";

const ai = new AI({ openAIApiKey: "" });
const client = new SingleStoreClient({ ai });
`

#### Additional Notes

- The SingleStoreClient class is flexible, allowing you to pass only the features you need (e.g., AI, API key). It will automatically configure the services based on the provided options.
- You can also use custom LLMs instead of the pre-installed OpenAI. To do this, see the @singlestore/ai package documentation.

---

$3

#### Get Current Organization

Returns the current organization if an API key was provided during initialization.

`ts
const organization = await client.organization.get();
`

---

$3

#### Get Workspace Group

##### All Workspace Groups

`ts
const workspaceGroups = await client.workspaceGroup.get();
`

##### By Workspace Group ID

`ts
const workspaceGroup = await client.workspaceGroup.get({
where: { id: "" },
});
`

##### By Workspace Group Name

`ts
const workspaceGroup = await client.workspaceGroup.get({
where: { name: "" },
});
`

##### Additional Notes

- To include terminated workspace groups, add the includeTerminated: true parameter to the workspaceGroup.get options object.
- To select specific fields from a workspace group, add the select: [''] parameter to the workspaceGroup.get options object.

---

#### Create Workspace Group

`ts
const { workspaceGroup, adminPassword } = await client.workspaceGroup.create({
name: "",
regionName: "US West 2 (Oregon)",
adminPassword: "",
allowAllTraffic: false,
firewallRanges: ["IP_ADDRESS"],
dataBucketKMSKeyID: "",
backupBucketKMSKeyID: "",
updateWindow: { day: "mo", hour: 12 },
expiresAt: new Date("2025-01-01"),
});
`

##### Additional Notes

- Only the name and regionName fields are required to create a workspace group. All other fields are optional.
- If the adminPassword value is not provided, a generated password is returned.
- To find all available regionName values, refer to this link.

---

#### Update Workspace Group

You can update a workspace group by specifying the workspace group ID or by calling the update method on a selected Workspace Group instance.

##### By Workspace Group ID

`ts
await client.workspaceGroup.update("", {
name: "",
adminPassword: "",
allowAllTraffic: true,
firewallRanges: [""],
updateWindow: { day: "mo", hour: 12 },
expiresAt: new Date("2025-01-01"),
});
`

##### Selected Workspace Group

Updates the currently selected workspace group.

`ts
await workspaceGroup.update({
name: "",
adminPassword: "",
allowAllTraffic: true,
firewallRanges: [""],
updateWindow: { day: "mo", hour: 12 },
expiresAt: new Date("2025-01-01"),
});
`

##### Additional Notes

- All fields are optional when updating a workspace group.

---

#### Delete Workspace Group

You can delete a workspace group by specifying the workspace group ID or by calling the delete method on a selected Workspace Group instance.

##### By Workspace Group ID

`ts
await client.workspaceGroup.delete("", false);
`

##### Selected Workspace Group

Deletes the currently selected workspace group.

`ts
await workspaceGroup.delete(false);
`

##### Additional Notes

- To forcibly delete a workspace group, set the optional force argument to true.

---

#### Get Metrics

`ts
const metrics = await workspaceGroup.getMetrics();
`

---

#### Get Private Connections

`ts
const privateConnections = await workspaceGroup.getPrivateConnections();
`

---

$3

#### Connect Workspace

##### Using Client

`ts
const connection = client.connect({
host: "",
user: "",
password: "",
port:
});
`

##### Using Workspace Group

`ts
const workspace = await workspaceGroup.workspace.get({
where: { id: "" },
});

if (workspace) {
const connection = workspace.connect({
user: "",
password: "",
port: ,
});
}
`

##### Free Tier

To connect to a free tier workspace, download the SSL certificate from this link, set the port and database, and place the SSL certificate in the root directory of your project.

`ts
const connection = client.connect({
host: "",
user: "",
password: "",
port:
database: "",
ssl: { ca: readFileSync(resolve(process.cwd(), "singlestore_bundle.pem")) },
});
`

---

#### Get Workspace

##### All Workspaces

`ts
const workspace = await workspaceGroup.workspace.get();
`

##### By Workspace ID

`ts
const workspace = await workspaceGroup.workspace.get({
where: { id: "" },
});
`

##### By Workspace Name

`ts
const workspace = await workspaceGroup.workspace.get({
where: { name: "" },
});
`

##### Additional Notes

- To include terminated workspaces, add the includeTerminated: true parameter to the workspaceGroup.workspace.get options object.
- To select specific fields from a workspace group, add the select: [''] parameter to the workspaceGroup.workspace.get options object.

---

#### Create Workspace

`ts
const workspace = await workspaceGroup.workspace.create({
name: "WORKSPACE_NAME",
size: "S-00",
enableKai: true,
cacheConfig: 1,
scaleFactor: 1,
autoSuspend: {
suspendType: "SCHEDULED",
suspendAfterSeconds: 1200,
},
});
`

##### Additional Notes

- Only the name field is required to create a workspace. All other fields are optional.
- To find all available size values, refer to the SingleStore Helios Pricing page.

---

#### Update Workspace

##### By Workspace ID

`ts
await workspaceGroup.workspace.update("", {
size: "S-00",
enableKai: true,
cacheConfig: 1,
scaleFactor: 1,
deploymentType: "PRODUCTION",
autoSuspend: {
suspendType: "SCHEDULED",
suspendAfterSeconds: 1200,
},
});
`

##### Selected Workspace

`ts
await workspace.update({
size: "S-00",
enableKai: true,
cacheConfig: 1,
scaleFactor: 1,
deploymentType: "PRODUCTION",
autoSuspend: {
suspendType: "SCHEDULED",
suspendAfterSeconds: 1200,
},
});
`

##### Additional Notes

- All fields are optional when updating a workspace.

---

#### Delete Workspace

##### By Workspace ID

`ts
await workspaceGroup.workspace.delete("");
`

##### Selected Workspace

`ts
await workspace.delete();
`

---

#### Get Workspace State

##### By Workspace ID

`ts
const state = await workspaceGroup.workspace.getState("");
`

##### Selected Workspace

`ts
const state = await workspace.getState();
`

---

#### Resume Workspace

##### By Workspace ID

`ts
await workspaceGroup.workspace.resume("", { disableAutoSuspend: false });
`

##### Selected Workspace

`ts
await workspace.resume({ disableAutoSuspend: false });
`

##### Additional Notes

- The disableAutoSuspend parameter is optional.

---

#### Suspend Workspace

##### By Workspace ID

`ts
await workspaceGroup.workspace.suspend("");
`

##### Selected Workspace

`ts
await workspace.suspend();
`

---

$3

#### Use Database

The use method allows you to interact with a specific database within the connection. You can optionally provide a generic DatabaseSchema to describe the database schema and its tables.

`ts
interface DatabaseSchema extends DatabaseType {
name: "";
tables: {
users: {
id: number;
};
};
}

const database = connection.database.use("");
`

---

#### Create Database

The create method allows you to create a database within the connection. You can optionally provide a generic DatabaseSchema to describe the database schema and its tables.

`ts
interface DatabaseSchema extends DatabaseType {
name: "";
tables: {
users: {
id: number;
};
};
}

const database = await connection.database.create({
name: "",
tables: {
users: {
columns: {
id: {
type: "BIGINT",
autoIncrement: true, // Optional
primaryKey: true, // Optional
nullable: false, // Optional
default: 0, // Optional
clauses: [""], // Optional
},
},
clauses: [""], // Optional
fulltextKeys: [""], // Optional
primaryKeys: [""], // Optional
},
},
});
`

---

#### Drop Database

##### By Database Name

`ts
await connection.database.drop("");
`

##### Selected Database

`ts
await database.drop();
`

---

#### Query Database

The query method allows you to execute a MySQL query on the database and retrieve the result. The query result is returned as an array of rows, where each row is represented as an object with column names as keys and the corresponding values.

`ts
type RowType = { [K: string]: any }[];

const [rows] = await database.query("");
`

##### Additional Notes

- Ensure that the query string is properly formatted to prevent SQL errors.
- The RowType is a flexible type that can accommodate various column structures in the query result.

---

#### Describe Database

`ts
const info = await database.describe();
`

---

#### Show Database Info

The showInfo method allows you to retrieve information about the database. You can optionally request extended information by setting the isExtended argument to true.

`ts
const info = await database.showInfo(true);
`

---

#### Show Database Tables Info

The showTablesInfo method allows you to retrieve information about the database tables. You can optionally request extended information by setting the isExtended argument to true.

`ts
const tablesInfo = await database.showTablesInfo(true);
`

---

$3

#### Use Table

The use method allows you to access a specific table within the database. It optionally accepts a table name and schema, providing an interface to interact with the table for querying and manipulation.

`ts
type TableName = "";
type TableSchema = { [K: string]: any };

const table = database.table.use("");
`

---

#### Create Table

The create method allows you to create a new table in the database. You can define the table name and schema, specifying columns and their properties such as data types, constraints, and default values.

`ts
type TableName = "";
type TableSchema = { id: number };

const table = await database.table.create({
name: "",
columns: {
id: {
type: "BIGINT",
autoIncrement: true, // Optional
primaryKey: true, // Optional
nullable: false, // Optional
default: 0, // Optional
clauses: [""], // Optional
},
},
});
`

---

#### Drop Table

##### By Table Name

`ts
await database.table.drop("");
`

##### Selected Table

`ts
await table.drop();
`

---

#### Truncate Table

##### By Table Name

`ts
await database.table.truncate("");
`

##### Selected Table

`ts
await table.truncate();
`

---

#### Rename Table

##### By Table Name

`ts
await database.table.rename("", "");
`

##### Selected Table

`ts
await table.rename("");
`

---

#### Show Table Info

The showInfo method allows you to retrieve information about the table. You can optionally request extended information by setting the isExtended argument to true.

`ts
const tableInfo = await table.showInfo(true);
`

---

#### Show Table Columns Info

The showInfo method allows you to retrieve information about the table columns.

`ts
const tableColumnsInfo = await table.showColumnsInfo();
`

---

#### Insert Table Value

The insert method allows you to insert data into a table. You can insert a single value or multiple values at once by providing an object or an array of objects that map column names to values.

##### Single Value

`ts
await table.insert({columnName: })
`

##### Multiple Values

`ts
await table.insert([{columnName: }, {columnName: }])
`

---

#### Find Table Values

The find method allows you to retrieve values from a table, with optional support for conditions, joins, grouping, ordering, and pagination. You can either fetch all values from a table or apply conditions to narrow down th

##### Find All Values

Retrieves all values from the table without any conditions.

`ts
const values = await table.find();
`

##### Find Values By Condition

Retrieves values from the table based on the specified conditions. You can customize the query with select, join, where, groupBy, orderBy, limit, and offset options.

`ts
const values = await table.find({
select: ["", "COUNT(*) AS count"], // Optional
join: [
{
type: "FULL", // Supported values: "INNER" | "LEFT" | "RIGHT" | "FULL"
table: "",
as: "",
on: [
"",
"=", // Supported values: "=" | "<" | ">" | "<=" | ">=" | "!="
"",
],
},
], // Optional
where: { columnName: "" }, // Optional
groupBy: [""], // Optional
orderBy: {
columnName: "asc", // Supported values: "asc" | "desc"
}, // Optional
limit: 10, // Optional
offset: 10, // Optional
});
`

##### Additional Notes

- The COUNT() AS count pattern follows the clause AS alias structure, where COUNT() is the clause and count is the alias.
- Ensure that joins, conditions, and selected columns are appropriate for the table schema and the data you're trying to retrieve.

---

#### Update Table Values

The update method allows you to modify existing values in the table. You provide the new values to update, along with a condition to specify which rows should be updated.

`ts
await table.update(
{ columnName: "" }, // New value
{ columnName: "" }, // Where condition
);
`

---

#### Delete Table Values

The delete method allows you to remove rows from the table that match a specified condition.

`ts
await table.delete({ columnName: "" });
`

##### Additional Notes

- Be cautious when using the delete method, especially if the where condition is broad, as it could result in the removal of multiple rows.
- If no where condition is provided, all rows in the table will be deleted. It’s best practice to always provide a where clause to avoid accidental data loss.

---

#### Table Vector Search

The vectorSearch method allows you to perform searches using vector-based embeddings in a specified column. This is particularly useful for tasks such as semantic search, where results are based on the similarity of vector representations of text or data.

##### Basic

Performs a vector search based on a prompt, returning rows from the table that match the vector similarity.

`ts
const rows = await table.vectorSearch({
prompt: "",
vectorColumn: "",
embeddingParams: {
model: "", // Optional
dimensions: "", // Optional
}, // Optional
});
`

##### With Conditions

Performs a vector search with additional conditions such as selected columns, joins, filtering, grouping, ordering, and pagination.

`ts
const rows = await table.vectorSearch(
{
prompt: "",
vectorColumn: "",
embeddingParams: {
model: "", // Optional
dimensions: "", // Optional
},
}, // Optional
{
select: [""], // Optional
join: [
{
type: "FULL", // Supported values: "INNER" | "LEFT" | "RIGHT" | "FULL"
table: "",
as: "",
on: [
"",
"=", // Supported values: "=" | "<" | ">" | "<=" | ">=" | "!="
"",
],
},
], // Optional
where: { columnName: "" }, // Optional
groupBy: [""], // Optional
orderBy: {
columnName: "asc", // Supported values: "asc" | "desc"
}, // Optional
limit: 10, // Optional
offset: 10, // Optional
}, // Optional
);
`

##### Additional Notes

- The vectorSearch method returns both the table rows and a v_score field, which reflects the similarity score of each row to the search prompt.
- Conditions such as select, join, where, and others can be used to refine the results further, similar to standard SQL queries.

---

#### Create Table Chat Completion

The createChatCompletion method allows you to generate chat completions based on a vector search within a table. Depending on the stream option, you can retrieve the results either as a complete string or in a streamed fashion, with optional custom tools for enhancing functionality.

##### As String

Performs a chat completion based on a vector search and returns the result as a complete string.

`ts
const chatCompletion = await table.createChatCompletion(
{
model: "", // Optional
prompt: "",
systemRole: "", // Optional
vectorColumn: "",
stream: false,
temperature: 0, // Optional
embeddingParams: {
model: "", // Optional
dimensions: "", // Optional
}, // Optional
},
{
select: [""], // Optional
where: { columnName: "" }, // Optional
limit: 1, // Optional
}, // Optional
);
`

##### As Stream

Performs a chat completion and returns the result as a stream of data chunks.

`ts
const stream = await table.createChatCompletion(
{
stream: true,
...
},
);

const chatCompletion = await ai.chatCompletions.handleStream(stream, (chunk) => {
console.log(chunk);
});
`

##### With Custom Tools

You can also integrate custom tools to extend the functionality of the chat completion.

`ts
import { ChatCompletionTool } from "@singlestore/ai/chat-completions";
import { z } from "zod";

const customTool = new ChatCompletionTool({
name: "",
description: "",
params: z.object({ paramName: z.string().describe("") }),
call: async (params) => {
const value = await anyFnCall(params);
return { name: "", params, value: JSON.stringify(value) };
},
});

await table.createChatCompletion({
tools: [customTool],
...
});
`

##### Additional Notes

- The second argument of the createChatCompletion method accepts the same options as the second argument of the vectorSearch method, such as select, where, and limit.
- When using stream: true, the handleStream function is used to process the stream. It accepts a callback as the second argument, which handles each new chunk of data as it arrives.

---

$3

##### Use Column

`ts
const column = table.column.use("");
`

---

#### Add Column

`ts
const column = await table.column.add({
name: "",
type: "BIGINT",
autoIncrement: false, // Optional
primaryKey: false, // Optional
nullable: true, // Optional
default: 0, // Optional
clauses: [""], // Optional
});
`

---

#### Modify Column

##### By Column Name

`ts
await table.column.modify("", {
type: "BIGINT",
autoIncrement: false, // Optional
primaryKey: false, // Optional
nullable: true, // Optional
default: 0, // Optional
clauses: [""], // Optional
});
`

##### Selected Column

`ts
await column.modify(...)
`

---

#### Rename Column

##### By Column Name

`ts
await table.column.rename("", "");
`

##### Selected Column

`ts
await column.modify("");
`

---

#### Drop Column

##### By Column Name

`ts
await table.column.drop("");
`

##### Selected Column

`ts
await column.drop();
`

---

#### Show Column Info

##### By Column Name

`ts
await table.column.showInfo("");
`

##### Selected Column

`ts
await column.showInfo();
`

---

$3

#### Get Billing

`ts
const billing = await client.billing.get({
metric: "ComputeCredit", // Supported values: "ComputeCredit" | "StorageAvgByte"
startTime: new Date("2024-01-01"),
endTime: new Date("2024-01-09"),
aggregateBy: "month", // Supported values: "hour", "day", "month"; Optional
});
`

---

$3

#### Get Region

##### Get All Regions

`ts
const regions = await client.region.get();
`

##### Get Region By ID

`ts
const region = await client.region.get({ id: "" });
`

##### Get Region By Name

`ts
const region = await client.region.get({ name: "" });
`

##### Additional Notes

- To find all available region names, follow this link

---

$3

#### Get Team

##### Get All Teams

`ts
const teams = await client.team.get();
`

##### Get Team By ID

`ts
const team = await client.team.get({ id: "" });
`

##### Get Team By Name

`ts
const team = await client.team.get({ name: "" });
`

##### Get Team By Description

`ts
const team = await client.team.get({ description: "" });
`

---

#### Create Team

`ts
const team = await client.team.create({
name: "",
description: "", // Optional
memberTeams: [""], // Optional
memberUsers: [""], // Optional
});
`

---

#### Update Team

##### By Team ID

`ts
await client.team.update("", {
name: "", // Optional
description: "", // Optional
});
`

##### Selected Team

`ts
await team.update(...);
`

---

#### Delete Team

##### By Team ID

`ts
await client.team.delete("");
`

##### Selected Team

`ts
await team.delete();
`

---

#### Add Team Member

##### Add Team

###### By Team ID

`ts
await client.team.addMemberTeams("", [""]);
`

###### Selected Team

`ts
await team.addMemberTeams([""]);
`

##### Add User

###### By Team ID

`ts
await client.team.addMemberUsers("", [""]);
`

###### Selected Team

`ts
await team.addMemberUsers([""]);
`

---

#### Remove Team Member

##### Remove Team

###### By Team ID

`ts
await client.team.removeMemberTeams("", [""]);
`

###### Selected Team

`ts
await team.removeMemberTeams([""]);
`

##### Remove User

###### By Team ID

`ts
await client.team.removeMemberUsers("", [""]);
`

###### Selected Team

`ts
await team.removeMemberUsers([""]);
`

---

$3

#### Get Job

`ts
const job = client.job.get("");
`

---

#### Create Job

`ts
const job = await client.job.create({
name: "", // Optional
description: "", // Optional
executionConfig: {
notebookPath: "",
createSnapshot: true,
runtimeName: "notebooks-cpu-small",
},
schedule: {
mode: "Recurring", // Supported values: "Once" | "Recurring"
executionIntervalInMinutes: 60,
startAt: new Date("2025-01-01"),
},
targetConfig: {
databaseName: "",
resumeTarget: true,
targetID: "",
targetType: "Workspace", // Supported values: "Workspace" | "Cluster" | "VirtualWorkspace"
}, // Optional
});
`

---

#### Delete Job

##### By Job ID

`ts
await client.job.delete("");
`

##### Selected Job

`ts
await job.delete();
`

---

#### Get Job Executions

##### By Job ID

`ts
const executions = await client.job.getExecutions("", 1, 10);
`

##### Selected Job

`ts
const executions = await job.getExecutions(1, 10);
`

---

#### Get Job Parameters

##### By Job ID

`ts
const parameters = await client.job.getParameters("");
`

##### Selected Job

`ts
const parameters = await job.getParameters();
`

---

#### Get Job Runtimes

`ts
const runtimes = await client.job.getRuntimes();
`

---

$3

#### Get Secret

##### Get All Secrets

`ts
const secrets = await client.secret.get();
`

##### Get By Secret ID

`ts
const secret = await client.secret.get({ id: "" });
`

##### Get By Secret Name

`ts
const secret = await client.secret.get({ name: "" });
`

---

#### Create Secret

`ts
const secret = await client.secret.create({
name: "",
value: "",
});
`

---

#### Update Secret

##### By Secret ID

`ts
const secret = await client.secret.update("", "");
`

##### Selected Secret

`ts
const secret = await secret.update("");
`

---

#### Delete Secret

##### By Secret ID

`ts
await client.secret.delete("");
`

##### Selected Secret

`ts
await secret.delete();
`

---

$3

- Folder path example: folderName/
- File path example: folderName/fileName.json

#### Get All Stage

`ts
const stage = await workspaceGroup.stage.get();
`

#### Get Stage Folder

`ts
const stage = await workspaceGroup.stage.get("/");
`

`ts
const nextStage = await stage.get("/");
`

#### Get Stage File

`ts
const stage = await workspaceGroup.stage.get("");
`

`ts
const nextStage = await stage.get("");
`

---

#### Update Stage

##### By Stage Path

`ts
await workspaceGroup.stage.update("", { newPath: "" });
`

##### Selected Stage

`ts
await stage.update({ newPath: "" });
`

##### Additional Notes

---

#### Create Stage Folder

##### In Stage Path

`ts
const newStage = await workspaceGroup.stage.createFolder("", "NEW_STAGE_NAME");
`

##### In Selected Stage

`ts
const newStage = stage.createFolder(
"",
"", // Optional
);
`

---

#### Delete Stage

##### By Stage Path

`ts
await workspaceGroup.stage.delete("");
`

##### Selected Stage

`ts
await stage.delete();
`

---

$3

#### Get Storage Regions

`ts
const regions = await workspaceGroup.storage.getRegions();
`

---

#### Get Storage Status

`ts
const status = await workspaceGroup.storage.getStatus();
`

---

$3

#### Execute Custom Query

`ts
const result = await connection.client.execute("");
``

---