JS/TS client v2
The TypeScript client is version v3.2.2
. Use the TypeScript v3 client for new projects.
The TypeScript client can be used for both JavaScript and TypeScript scripts.
Installation and setup
To install the TypeScript client library package, use npm.
npm install weaviate-ts-client
Usage and type definitions
Once installed, you can use the client in your TypeScript and JavaScript scripts, as shown in the following examples.
Usage
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your Weaviate endpoint
});
client
.schema
.getter()
.do()
.then(res => {
console.log(res);
})
.catch(err => {
console.error(err)
});
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your Weaviate endpoint
});
const response = await client
.schema
.getter()
.do();
console.log(response);
If you are having any issues with the import statement in TypeScript (e.g. if weaviate
is undefined
), try adding "esModuleInterop": true
to your "compilerOptions"
in tsconfig.json
.
Type definitions
The type definitions can be found under the types
subdirectory of the package in the *.d.ts
files, for example as shown on the npm package page.
Authentication
For more comprehensive information on configuring authentication with Weaviate, refer to the authentication page.
The TypeScript client offers multiple options for authenticating against Weaviate, including multiple OIDC authentication flows.
The suitable authentication options and methods for the client largely depend on the specific configuration of the Weaviate instance.
API key authentication
If you use an API key to authenticate, instantiate the client like this:
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
// Instantiate the client with the auth config
const client = weaviate.client({
scheme: 'https',
host: 'edu-demo.weaviate.network', // Replace with your Weaviate endpoint
apiKey: new weaviate.ApiKey('learn-weaviate'), // Replace with your Weaviate instance API key
});
import weaviate, { WeaviateClient, ApiKey } from 'weaviate-ts-client';
// Instantiate the client with the auth config
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'edu-demo.weaviate.network', // Replace with your Weaviate endpoint
apiKey: new ApiKey('learn-weaviate'), // Replace with your Weaviate instance API key
});
OIDC authentication
To authenticate against Weaviate with OIDC, you must select a flow made available by the identity provider and create the flow-specific authentication configuration.
This configuration will then be used by the Weaviate client to authenticate. The configuration includes secrets that help the client obtain an access token
and, if configured, a refresh token
.
The access token
is added to the HTTP header of each request and is utilized for authentication with Weaviate. Typically, this token has a limited lifespan, and the refresh token
can be employed to obtain a new set of tokens when necessary.
When using OIDC with the TypeScript client, its background token refresh process can block a script from exiting. If this behavior is not desired, you can:
- Set the
silentRefresh
parameter asfalse
in the OIDC configuration. Or, - Stop the process via
client.oidcAuth?.stopTokenRefresh()
, e.g. when a script is expected to exit, or token refresh is no longer needed.
Resource Owner Password Flow
This OIDC flow uses the username and password to obtain required tokens for authentication.
Note that not every provider automatically includes a refresh token
and an appropriate scope might be required that depends on your identity provider. The client uses offline_access as the default scope. This works with some providers, but as it depends on the configuration of the identity providers, we ask you to refer to the identity provider's documentation.
Without a refresh token, there is no possibility to acquire a new access token
and the client becomes unauthenticated after expiration.
The Weaviate client does not save the username or password used.
They are only used to obtain the first tokens, after which existing tokens will be used to obtain subsequent tokens if possible.
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new weaviate.AuthUserPasswordCredentials({
username: 'user123',
password: 'password',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['offline_access'] // optional, depends on the configuration of your identity provider (not required with WCD)
})
});
import weaviate, { WeaviateClient, AuthUserPasswordCredentials } from 'weaviate-ts-client';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new AuthUserPasswordCredentials({
username: 'user123',
password: 'password',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['offline_access'] // optional, depends on the configuration of your identity provider (not required with WCD)
})
});
Client Credentials flow
This OIDC flow uses a client secret
to obtain required tokens for authentication.
This flow is recommended for server-to-server communication without end-users and authenticates an application to Weaviate. This authentication flow is typically regarded as more secure than the resource owner password flow: a compromised client secret can be simply revoked, whereas a compromised password may have larger implications beyond the scope of breached authentication.
To authenticate a client secret most identity providers require a scope to be specified. This scope depends on the configuration of the identity providers, so we ask you to refer to the identity provider's documentation.
Most providers do not include a refresh token in their response so client secret
is saved in the client to obtain a new access token
on expiration of the existing one.
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new weaviate.AuthClientCredentials({
clientSecret: 'supersecuresecret',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['scope1', 'scope2'] // optional, depends on the configuration of your identity provider
})
});
import weaviate, { WeaviateClient, AuthClientCredentials } from 'weaviate-ts-client';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new AuthClientCredentials({
clientSecret: 'supersecuresecret',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
scopes: ['scope1', 'scope2'] // optional, depends on the configuration of your identity provider
})
});
Refresh Token flow
Any other OIDC authentication method can be used to obtain tokens directly from your identity provider, for example by using this step-by-step guide of the hybrid flow.
If no refresh token
is provided, there is no possibility to obtain a new access token
and the client becomes unauthenticated after expiration.
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new weaviate.AuthAccessTokenCredentials({
accessToken: 'abcd1234',
expiresIn: 900,
refreshToken: 'efgh5678',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
})
});
import weaviate, { WeaviateClient, AuthAccessTokenCredentials } from 'weaviate-ts-client';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
authClientSecret: new AuthAccessTokenCredentials({
accessToken: 'abcd1234',
expiresIn: 900,
refreshToken: 'efgh5678',
silentRefresh: true, // Default: true - if false, you must refresh the token manually; if true, this background process will prevent a script from exiting.
})
});
Custom headers
You can pass custom headers to the client, which are added at initialization:
- JavaScript
- TypeScript
const { default: weaviate } = require('weaviate-ts-client');
const client = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
headers: { headerName: 'HeaderValue' }
});
import weaviate, { WeaviateClient } from 'weaviate-ts-client';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your instance URL
headers: { headerName: 'HeaderValue' }
});
These headers will then be included in every request that the client makes.
References
Some older code examples are written in JavaScript and have not been updated yet. Newer code examples use TypeScript.
Our RESTful endpoints and GraphQL functions covered by the TypeScript client currently have JavaScript examples in the code blocks.
Design
Builder pattern
The TypeScript client is designed following the Builder pattern. The pattern is used to build complex query objects. This means that calls (for example to retrieve data with a RESTful GET request, or using a more complex GraphQL query) are built with chained objects to reduce complexity. Some builder objects are optional, others are required to perform specific functions. Builder examples can be found in the RESTful API reference pages and the GraphQL reference pages.
The code snippet at the top of this page shows a simple query corresponding to the RESTful request GET /v1/schema
. The client is initialized by requiring the package and connecting to a local instance. Then, a query is constructed by getting the .schema
with .getter()
. The query will be sent with the .do()
call. do()
is required for every function you want to build and execute.
General notes
- All methods use ES6 Promises to deal with asynchronous code, so you need to use
.then()
after function calls, or haveasync
/await
support. - In the case of an error, the Promise rejects with the specific error message. (If using
async
/await
, a rejected promises acts like a thrown exception). - Internally the client uses
isomorphic-fetch
to make the REST calls, so it should work from both the browser and NodeJS applications without any required changes.
TypeScript for JavaScript users
TypeScript is a superset of JavaScript. There are, however, some differences that you should be aware of. This section offers some suggestions for JavaScript users who are new to TypeScript.
Run a TypeScript file
To run a TypeScript file, first convert it to JavaScript. The typescript
package from npm
includes the tsc
utility. Use tsc
to convert (transpile) the TypeScript file.
Install the typescript
package. Add the -g
flag if you want the package to be available globally.
npm install typescript
Some packages, like the Weaviate TypeScript client, require extra configuration. The root directory of a TypeScript project has a tsconfig.json
file. Add the following to your tsconfig.json
.
Compiler options
"target": "esnext"
"module": "esnext"
"moduleResolution": "node"
"include": ["*.ts"]
(Or specific files)"lib": [ "es2018" ]
Don't specify filenames on the command line when you use tsconfig.json
. Specify the TypeScript files in tsconfig.json
instead. tsc
only reads tsconfig.json
when you run it by itself.
tsc
node
only allows the import
statement in modules. To allow the import
statement, add the following to your package.json
file.
{
"type": "module"
}
Example
To run this example, complete these steps.
- Install the
typescript
package. - Update the
tsconfig.json
andpackage.json
files as described above. - Copy the sample code.
- Save the code as
sample.ts
in the same directory astsconfig.json
andpackage.json
. - Convert and run the code.
Use this code to create sample.ts
.
Sample TypeScript code
import weaviate from 'weaviate-ts-client';
const client = weaviate.client({
scheme: 'https',
host: 'edu-demo.weaviate.network',
apiKey: new weaviate.ApiKey('learn-weaviate'),
});
console.log(client.misc)
Convert sample.ts
.
tsc
Run the converted file.
node sample.js
The output looks like this.
Sample output
{
"clientId": "wcs",
"href": "https://auth.wcs.api.weaviate.io/auth/realms/SeMI/.well-known/openid-configuration"
}
Client releases
Click here for a table of Weaviate and corresponding client versions
This table lists the Weaviate core versions and corresponding client library versions.
Weaviate (GitHub) | First release date | Python (GitHub) | TypeScript/ JavaScript (GitHub) | Go (GitHub) | Java (GitHub) |
---|---|---|---|---|---|
1.27.x | 2024-10-16 | 4.9.x | 3.2.x | 4.16.x | 4.9.x |
1.26.x | 2024-07-22 | 4.7.x | 3.1.x | 4.15.x | 4.8.x |
1.25.x | 2024-05-10 | 4.6.x | 2.1.x | 4.13.x | 4.6.x |
1.24.x | 2024-02-27 | 4.5.x | 2.0.x | 4.10.x | 4.4.x |
1.23.x | 2023-12-18 | 3.26.x | 1.5.x | 4.10.x | 4.4.x |
1.22.x | 2023-10-27 | 3.25.x | 1.5.x | 4.10.x | 4.3.x |
1.21.x | 2023-08-17 | 3.22.x | 1.4.x | 4.9.x | 4.2.x |
1.20.x | 2023-07-06 | 3.22.x | 1.1.x | 4.7.x | 4.2.x |
1.19.x | 2023-05-04 | 3.17.x | 1.1.x1 | 4.7.x | 4.0.x |
1.18.x | 2023-03-07 | 3.13.x | 2.14.x | 4.6.x | 3.6.x |
1.17.x | 2022-12-20 | 3.9.x | 2.14.x | 4.5.x | 3.5.x |
1.16.x | 2022-10-31 | 3.8.x | 2.13.x | 4.4.x | 3.4.x |
1.15.x | 2022-09-07 | 3.6.x | 2.12.x | 4.3.x | 3.3.x |
1.14.x | 2022-07-07 | 3.6.x | 2.11.x | 4.2.x | 3.2.x |
1.13.x | 2022-05-03 | 3.4.x | 2.9.x | 4.0.x | 2.4.x |
1.12.x | 2022-04-05 | 3.4.x | 2.8.x | 3.0.x | 2.3.x |
1.11.x | 2022-03-14 | 3.2.x | 2.7.x | 2.6.x | 2.3.x |
1.10.x | 2022-01-27 | 3.1.x | 2.5.x | 2.4.x | 2.1.x |
1.9.x | 2021-12-10 | 3.1.x | 2.4.x | 2.4.x | 2.1.x |
1.8.x | 2021-11-30 | 3.1.x | 2.4.x | 2.3.x | 1.1.x |
1.7.x | 2021-09-01 | 3.1.x | 2.4.x | 2.3.x | 1.1.x |
1.6.x | 2021-08-11 | 2.4.x | 2.3.x | 2.2.x | 1.0.x |
1.5.x | 2021-07-13 | 2.2.x | 2.1.x | 2.1.x | 1.0.x |
1.4.x | 2021-06-09 | 2.2.x | 2.1.x | 2.1.x | 1.0.x |
1.3.x | 2021-04-23 | 2.2.x | 2.1.x | 2.1.x | 1.0.x |
1.2.x | 2021-03-15 | 2.2.x | 2.0.x | 1.1.x | - |
1.1.x | 2021-02-10 | 2.1.x | - | - | - |
1.0.x | 2021-01-14 | 2.0.x | - | - | - |
Client change logs
The client change logs for each release are available on GitHub.
Questions and feedback
If you have any questions or feedback, let us know in the user forum.