No native modules, pod install, or Android linking steps are required. The package targets Node.js 18+ (ESM and CJS both supported via the package exports map).

Project setup

1. Copy the source/ directory into your project, e.g. src/weaviate/.

2. In tsconfig.json ensure:

{
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "Node16",
    "target": "ES2020",
    "esModuleInterop": true,
    "strict": true
  }
}

3. If you use path aliases, add a mapping:

{
  "compilerOptions": {
    "paths": {
      "weaviate-client": ["./src/weaviate/index.ts"]
    }
  }
}

4. Set environment variables for your Weaviate instance:

WEAVIATE_HOST=localhost
WEAVIATE_PORT=8080
WEAVIATE_GRPC_PORT=50051
WEAVIATE_API_KEY=your-api-key   # optional

5. Import and connect (see examples below). No build-time code generation is required; the protobuf stubs are pre-generated in proto/.

Public API

ConnectToLocalOptions

import { ConnectToLocalOptions } from './connection/helpers.js';

type ConnectToLocalOptions = {
  host?: string;
  port?: number;
  grpcPort?: number;
  headers?: Headers;
  authCredentials?: AuthCredentials;
};

Passed to connectToLocal() to point the client at a self-hosted instance. Use this during local development or when running Weaviate in Docker.

ApiKey / AuthCredentials

import { ApiKey, AuthCredentials } from './connection/auth.js';

const creds: AuthCredentials = new ApiKey('your-api-key');

ApiKey is the simplest credential type. AuthCredentials is the union of ApiKey, AuthAccessTokenCredentials, AuthClientCredentials, and AuthUserPasswordCredentials. Pass any of them as authCredentials in a connect helper.

Aliases (alias module)

import alias, { Aliases } from './alias/index.js';

interface Aliases {
  create: (args: { collection: string; alias: string }) => Promise<void>;
  listAll: (opts?: { collection?: string })        => Promise<Alias[] | undefined>;
  get:     (alias: string)                          => Promise<Alias>;
  update:  (args: { alias: string; newTargetCollection: string }) => Promise<void>;
  delete:  (alias: string)                          => Promise<void>;
}

Use when you need to expose a stable name that can be hot-swapped to a new collection without changing downstream consumers.

Backup (backup module)

import backup, { Backend, BackupStatus } from './backup/index.js';

type Backend      = 'filesystem' | 's3' | 'gcs' | 'azure';
type BackupStatus = 'STARTED' | 'TRANSFERRING' | 'TRANSFERRED' | 'SUCCESS' | 'FAILED';

interface Backup {
  creator:           () => BackupCreator;
  createStatusGetter:() => BackupCreateStatusGetter;
  restorer:          () => BackupRestorer;
  restoreStatusGetter:() => BackupRestoreStatusGetter;
}

Use creator() to kick off a backup and createStatusGetter() to poll until SUCCESS or FAILED.

Batch (batch module)

import batch, { DeleteOutput, DeleteResultStatus } from './batch/index.js';

interface Batch {
  objectsBatcher:        () => ObjectsBatcher;
  objectsBatchDeleter:   () => ObjectsBatchDeleter;
  referencesBatcher:     () => ReferencesBatcher;
  referencePayloadBuilder:() => ReferencePayloadBuilder;
}

Use for high-throughput object ingestion or deletion to avoid per-request overhead.

Working examples

Scenario - Connect and manage aliases

Connect to a local Weaviate instance and swap a collection alias atomically.

import weaviate from 'weaviate-client';

async function swapAlias() {
  const client = await weaviate.connectToLocal({
    host: process.env.WEAVIATE_HOST ?? 'localhost',
    port: Number(process.env.WEAVIATE_PORT ?? 8080),
    grpcPort: Number(process.env.WEAVIATE_GRPC_PORT ?? 50051),
  });

  const aliases = client.alias;

  // Create an alias pointing at the current live collection
  await aliases.create({ collection: 'ArticlesV1', alias: 'Articles' });

  // Later: redirect the alias to a freshly built collection
  await aliases.update({ alias: 'Articles', newTargetCollection: 'ArticlesV2' });

  // Inspect all aliases
  const all = await aliases.listAll();
  console.log(all);

  await client.close();
}

swapAlias().catch(console.error);

Scenario - Trigger and poll a backup

Kick off an S3 backup and poll until completion.

import weaviate from 'weaviate-client';
import { BackupStatus } from './backup/index.js';

async function runBackup() {
  const client = await weaviate.connectToLocal();
  const bkp = client.backup;

  // Start backup
  const creator = bkp.creator();
  await creator
    .withBackend('s3')
    .withBackupId('nightly-2024-01-01')
    .withIncludeClassNames(['Articles', 'Authors'])
    .do();

  // Poll status
  const statusGetter = bkp.createStatusGetter();
  let status: BackupStatus = 'STARTED';

  while (status !== 'SUCCESS' && status !== 'FAILED') {
    await new Promise((r) => setTimeout(r, 2000));
    const result = await statusGetter
      .withBackend('s3')
      .withBackupId('nightly-2024-01-01')
      .do();
    status = result.status as BackupStatus;
    console.log('Backup status:', status);
  }

  await client.close();
}

runBackup().catch(console.error);

Scenario - Bulk object ingestion with ApiKey auth

Connect to Weaviate Cloud and insert objects in batch.

import weaviate from 'weaviate-client';
import { ApiKey } from './connection/auth.js';

async function bulkIngest() {
  const client = await weaviate.connectToWeaviateCloud(
    'https://my-cluster.weaviate.network',
    {
      authCredentials: new ApiKey(process.env.WEAVIATE_API_KEY ?? ''),
    }
  );

  const batcher = client.batch.objectsBatcher();

  for (let i = 0; i < 500; i++) {
    batcher.withObject({
      class: 'Article',
      properties: { title: `Article ${i}`, body: `Content ${i}` },
    });
  }

  const result = await batcher.do();
  console.log(`Inserted ${result.length} objects`);

  await client.close();
}

bulkIngest().catch(console.error);

File walkthrough

• alias/ - Implements Aliases interface: create/list/get/update/delete alias operations over REST.
• backup/ - BackupCreator and BackupRestorer builders plus status-polling getters for backup lifecycle.
• batch/ - ObjectsBatcher, ObjectsBatchDeleter, ReferencesBatcher, and ReferencePayloadBuilder for bulk writes.
• c11y/ - Contextionary API: ConceptsGetter fetches word vectors; ExtensionCreator adds custom concepts.
• classifications/ - Scheduler triggers kNN/zero-shot classification; Getter retrieves job status.
• cluster/ - NodesStatusGetter returns per-node shard and object statistics.
• collections/ - The richest module: query, aggregate, configure, data CRUD, filters, generate (RAG), iterator, references, serialize/deserialize, sort, tenants, and vector management.
• connection/ - HTTP and gRPC connection classes, all auth credential types, and the connectTo* helper factories.
• data/ - ConsistencyLevel enum (ONE, QUORUM, ALL) for replication-aware reads/writes.
• graphql/ - Fluent builders for Get, Aggregate, Explore, and Raw GraphQL queries.
• groups/ - Group CRUD operations.
• grpc/ - Low-level gRPC channel setup and interceptors.
• misc/ - LiveChecker, ReadyChecker, and OpenidConfigurationGetter for health and OIDC discovery.
• openapi/ - Auto-generated TypeScript types matching the Weaviate OpenAPI spec.
• proto/ - Pre-generated protobuf/gRPC stubs; do not hand-edit.
• roles/ - Role and permission management with a permissions helper for constructing permission objects.
• schema/ - Legacy v1 schema CRUD (class, property, shard management).
• users/ - User creation, deletion, and role assignment.
• utils/ - DbVersion detection, BeaconPath construction, and other internal helpers.
• v2/ - Thin wrapper exposing the older v2-style client for backwards compatibility.
• validation/ - Common input guards used across builders.
• errors.ts - Typed error classes (WeaviateError, WeaviateInvalidInputError, etc.).
• index.ts - Aggregates and re-exports everything; the single import surface for consumers.
• version.ts - Exports the CLIENT_VERSION string constant.

Common pitfalls and fixes

• ESM .js extensions in imports: The source uses import ... from './foo.js' even in .ts files. If your bundler or ts-node complains, set "moduleResolution": "Node16" or "Bundler" in tsconfig.json.
• gRPC port not set: Forgetting grpcPort causes silent fallback to HTTP-only mode; always pass grpcPort: 50051 (or your configured port) explicitly in ConnectToLocalOptions.
• ApiKey vs OIDC: Passing a plain string instead of new ApiKey(...) to authCredentials will throw at runtime; always construct the credential object.
• connectToWeaviateCloud URL format: The URL must include the scheme (https://). Omitting it causes a malformed-URL error in the connection layer.
• Backup backend credentials: BackupCreator does not accept cloud credentials directly; configure the backend credentials in your Weaviate server's environment variables (BACKUP_S3_BUCKET, etc.).
• Node.js version: The gRPC transport (nice-grpc) requires Node.js 18+. Running on Node 16 will cause ERR_UNSUPPORTED_ESM_URL_SCHEME or missing fetch errors.

Vibe-coding prompt template

I have dropped the Weaviate TypeScript client source into `src/weaviate/` in my project.
The USAGE.md for this block is at `src/weaviate/USAGE.md`.
The upstream package is `user@example.com`.

Please integrate the client into my project step by step:

1. Read `src/weaviate/USAGE.md` and `src/weaviate/index.ts` to understand available exports.
2. Install all required npm dependencies listed in USAGE.md § "Required dependencies".
3. Update `tsconfig.json` as described in USAGE.md § "Project setup".
4. Create `src/db.ts` that connects to Weaviate using `connectToLocal()` (or `connectToWeaviateCloud()` if I am targeting WCD) and exports a singleton `client`.
5. Wire the `client.alias`, `client.backup`, and `client.batch` APIs into my existing service layer, following the patterns in USAGE.md § "Working examples".
6. Do not invent any exports. Only use symbols documented in USAGE.md § "Public API" and visible in `src/weaviate/index.ts`.
7. Show the final file diff for each changed file.

License and credit

The upstream project is licensed under the BSD 3-Clause License (see source/LICENSE if present, or the GitHub repository). This block is derived from user@example.com published by Weaviate B.V.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。