@ datastax/ astra- db- ts
astra-db-ts 是用于交互的 TypeScript 客户端 数据税 Astra DB。 。 。 .
这个README目标v2.0.0+,扩展了之前的 1.x API. 点击 这里 对于先前存在的客户端读取.
目录
快速启动
使用您首选的软件包管理器安装 @datastax/astra-db-ts。 。 。 .
npm i @datastax/astra-db-ts # or your favorite package manager's equivalent
如果您使用 TypeScript, 您必须至少使用 5. 0.0 版本才能使用 astra-db-ts 2.0,因为它使用现代类型脚本特性,例如 const 类型参数.
npm i typescript@^5.0.0
拿着 API 终点 还有你的 应用程序符号 用于您的 Astra DB 实例 @ astra.datastax.com (英语)。 。 。 .
收款
import { DataAPIClient, ObjectId, vector, VectorDoc, oid } from '@datastax/astra-db-ts';
// Connect to the db
const client = new DataAPIClient({ logging: 'all' });
const db = client.db(process.env.CLIENT_DB_URL!, { token: process.env.CLIENT_DB_TOKEN! });
// The `VectorDoc` interface adds `$vector?: DataAPIVector` as a field to the collection type
interface Dream extends VectorDoc {
_id: ObjectId,
summary: string,
tags?: string[],
}
(async () => {
// Create the collection with a custom default ID type
const collection = await db.createCollection<Dream>('dreams', {
defaultId: { type: 'objectId' },
});
// Batch-insert some rows into the table.
// _id can be optionally provided, or be auto-generated @ the server side
await collection.insertMany([{
summary: 'A dinner on the Moon',
$vector: vector([0.2, -0.3, -0.5]),
}, {
summary: 'Riding the waves',
$vector: vector([0, 0.2, 1]),
tags: ['sport'],
}, {
_id: oid('674f0f5c1c162131319fa09e'),
summary: 'Meeting Beethoven at the dentist',
$vector: vector([0.2, 0.6, 0]),
}]);
// Hm, changed my mind
await collection.updateOne({ _id: oid('674f0f5c1c162131319fa09e') }, {
$set: { summary: 'Surfers\' paradise' }
});
// Let's see what we've got, by performing a vector search
const cursor = collection.find({})
.sort({ vector: vector([0, 0.2, 0.4]) })
.includeSimilarity(true)
.limit(2);
// This would print:
// - Surfers' paradise: 0.98238194
// - Friendly aliens in town: 0.91873914
for await (const result of cursor) {
console.log(`${result.summary}: ${result.$similarity}`);
}
// Cleanup (if desired)
await collection.drop();
})();
表格
import { DataAPIClient, InferTableSchema, Table, vector } from '@datastax/astra-db-ts';
// Connect to the db
const client = new DataAPIClient({ logging: 'all' });
const db = client.db(process.env.CLIENT_DB_URL!, { token: process.env.CLIENT_DB_TOKEN! });
// Define the table's schema so we can infer the type of the table automatically (TS v5.0+)
const DreamsTableSchema = Table.schema({
columns: {
id: 'int',
summary: 'text',
tags: { type: 'set', valueType: 'text' },
vector: { type: 'vector', dimension: 3 },
},
primaryKey: 'id',
});
// Infer the TS-equivalent type from the table definition (like zod or arktype). Equivalent to:
//
// interface TableSchema {
// id: number,
// summary?: string | null,
// tags?: Set<string>,
// vector?: DataAPIVector | null,
// }
type Dream = InferTableSchema<typeof DreamsTableSchema>;
(async () => {
// Create the table if it doesn't already exist
// Table will be typed as `Table<Dream, { id: number }>`, where the former is the schema, and the latter is the primary key
const table = await db.createTable('dreams', {
definition: DreamsTableSchema,
ifNotExists: true,
});
// Create a vector index on the vector column so we can perform ANN searches on the table
await table.createVectorIndex('dreams_vector_idx', 'vector', {
options: { metric: 'cosine' },
ifNotExists: true,
});
// Batch-insert some rows into the table
const rows: Dream[] = [{
id: 102,
summary: 'A dinner on the Moon',
vector: vector([0.2, -0.3, -0.5]),
}, {
id: 103,
summary: 'Riding the waves',
vector: vector([0, 0.2, 1]),
tags: new Set(['sport']),
}, {
id: 37,
summary: 'Meeting Beethoven at the dentist',
vector: vector([0.2, 0.6, 0]),
}];
await table.insertMany(rows);
// Hm, changed my mind
await table.updateOne({ id: 103 }, {
$set: { summary: 'Surfers\' paradise' }
});
// Let's see what we've got, by performing a vector search
const cursor = table.find({})
.sort({ vector: vector([0, 0.2, 0.4]) })
.includeSimilarity(true)
.limit(2);
// This would print:
// - Surfers' paradise: 0.98238194
// - Friendly aliens in town: 0.91873914
for await (const result of cursor) {
console.log(`${result.summary}: ${result.$similarity}`);
}
// Cleanup (if desired)
await table.drop();
})();
今后的步骤
高级别建筑
astra-db-ts用于在数据层和管理员层工作的抽象结构由本图所描述:
flowchart TD
DataAPIClient -->|".db(endpoint)"| Db
DataAPIClient -->|".admin()"| AstraAdmin
Db --->|".collection(name)
.createCollection(name)"| Collection
Db --->|".table(name)
.createTable(name)"| Table
AstraAdmin -->|".dbAdmin(endpoint)
.dbAdmin(id, region)"| DbAdmin
Db -->|".admin()"| DbAdmin
DbAdmin -->|".db()"| Db
以下是一个面向行政的小例子:
import { DataAPIClient } from '@datastax/astra-db-ts';
// Spawn an admin
const client = new DataAPIClient('*TOKEN*');
const admin = client.admin();
(async () => {
// list info about all databases
const databases = await admin.listDatabases();
const dbInfo = databases[0];
console.log(dbInfo.name, dbInfo.id, dbInfo.regions);
// list keyspaces for the first database
const dbAdmin = admin.dbAdmin(dbInfo.id, dbInfo.regions[0].name);
console.log(await dbAdmin.listKeyspaces());
})();
选项等级
和客户端的等级一样,每个类的选项也存在于一个等级中.
家长班的一般选择与子女班的选择紧密结合.
graph TD
DataAPIClientOptions --> AdminOptions
DataAPIClientOptions --> DbOptions
DbOptions --> CollectionOptions
DbOptions --> TableOptions
数据类型
见 数据 用于完整列表支持的数据类型及其类型脚本等同.
非支助
astra-db-ts 官方支持使用非AStra后端的数据 API 实例,例如DSE或HCD上的数据 API.
然而,虽然支持是本地的,但检测不是;您有时必须手动宣布环境.
import { DataAPIClient, UsernamePasswordTokenProvider, DataAPIDbAdmin } from '@datastax/astra-db-ts';
// You'll need to pass in environment to the DataAPIClient when not using Astra
const tp = new UsernamePasswordTokenProvider('*USERNAME*', '*PASSWORD*');
const client = new DataAPIClient(tp, { environment: 'dse' });
const db = client.db('*ENDPOINT*');
// A common idiom may be to use `dbAdmin.createKeyspace` with `updateDbKeyspace` to initialize the keyspace when necessary
const dbAdmin = db.admin({ environment: 'dse' });
dbAdmin.createKeyspace('...', { updateDbKeyspace: true });
这个 TokenProvider 类是一个可扩展的概念,允许您创建甚至刷新您的符号
,视数据 API 后端而定。 必要时甚至可以省略指指针.
astra-db-ts 提供两个 TokenProvider 默认实例 :
StaticTokenProvider- 这个单位提供商只是重新加价 任何信物被传递到它的构造器UsernamePasswordTokenProvider- 将用户/通道对对转换成 DSE/HCD 的适当符号
(见 examples/non-astra-backends 以充分的例子说明这一点。 )
浏览器支持
astra-db-ts 设计在服务器侧环境工作,但它也可以在浏览器中技术上工作.
但是,如果出于某种原因,你真想在浏览器中使用这个,你可能需要安装 events 混合填充器,
并可能设立CORS代理(例如: (简体中文) 任何地方)向数据API转发请求.
但记住,这可能是非常不安全的, 特别是如果你硬编码敏感数据 进入你的客户端 代码,因为任何人检查代码并取出信使(通过XSS攻击或其他方式)是微不足道的.
见 examples/browser 浏览器在操作中的用法,以及如何使用的步骤 astra-db-ts 在您的浏览器应用程序中.
使用 HTTP/2
astra-db-ts 使用本地语言 fetch API 默认,但它也可以与 HTTP/2 使用 fetch-h2 模块.
然而,由于兼容性的原因, fetch-h2 默认不再动态导入,必须手动提供给客户端.
幸运的是,只有几步容易走 HTTP/2 在您的项目中工作 :
- 安装
fetch-h2通过运行npm i fetch-h2。 。 。 . - 提供
fetch-h2给客户的.
import * as fetchH2 from 'fetch-h2';
// or `const fetchH2 = require('fetch-h2');`
const client = new DataAPIClient({
httpOptions: {
client: 'fetch-h2',
fetchH2: fetchH2,
},
});
见 使用 HTTP/2 实例 并提供更多关于如何使用的信息 astra-db-ts 与 HTTP/2。 。 。 .
实例
看看这个 实例 更多如何使用的实例的目录 astra-db-ts 在自己的项目.