@upstash/vector 0.1.0-alpha-8 → 0.1.0-alpha-9

package/README.md

@@ -118,6 +118,8 @@ type UpstashRecord = {
 };
 ```
 
+#### Upsert many
+
 To upsert some records, you can use the client like so:
 
 ```typescript
@@ -141,6 +143,22 @@ const records = [
 await index.upsert(records);
 ```
 
+#### Upsert one
+
+```typescript
+const index = new Index();
+
+// Prepare your data. The length of each array
+// of vector values must match the dimension of
+// the index where you plan to store them.
+const record = {
+  id: "1",
+  vector: [0.236, 0.971, 0.559],
+};
+// Upsert the data into your index
+await index.upsert(record);
+```
+
 ### Querying
 
 #### Querying with vector values
@@ -219,3 +237,11 @@ await index.delete("id-to-delete");
 ```typescript
 await index.delete(["id-1", "id-2", "id-3"]);
 ```
+
+### Stats
+
+To get statistics of your index, you can use the client like so:
+
+```typescript
+await index.stats(["id-1", "id-2", "id-3"]);
+```

package/dist/index.d.mts

@@ -42,7 +42,7 @@ type RequesterConfig = {
     cache?: CacheSetting;
 };
 
-declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range"];
+declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range", "stats"];
 type EndpointVariants = (typeof ENDPOINTS)[number];
 /**
  * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
@@ -63,6 +63,14 @@ declare class DeleteCommand extends Command<{
     constructor(id: (number[] | string[]) | number | string);
 }
 
+type Vector<TMetadata = Record<string, unknown>> = {
+    id: string;
+    vector: number[];
+    metadata?: TMetadata;
+};
+
+type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null;
+
 type QueryCommandPayload = {
     vector: number[];
     topK: number;
@@ -88,14 +96,6 @@ declare class UpsertCommand extends Command<string> {
     constructor(payload: UpsertCommandPayload | UpsertCommandPayload[]);
 }
 
-type Vector<TMetadata> = {
-    id: string;
-    vector: number[];
-    metadata?: TMetadata;
-};
-
-type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null;
-
 type RangeCommandPayload = {
     cursor: number | string;
     limit: number;
@@ -110,6 +110,12 @@ declare class RangeCommand<TMetadata> extends Command<RangeResult<TMetadata>> {
     constructor(payload: RangeCommandPayload);
 }
 
+type StatsResult = {
+    vectorCount: number;
+    pendingVectorCount: number;
+    indexSize: number;
+};
+
 type CommandArgs<TCommand extends new (_args: any) => any> = ConstructorParameters<TCommand>[0];
 /**
  * Serverless vector client for upstash vector db.
@@ -244,6 +250,18 @@ declare class Index$1 {
      * @returns {Promise<RangeReturnResponse<TMetadata>>} A promise that resolves with the response containing the next cursor and an array of vectors, after the command is executed.
      */
     range: (args: CommandArgs<typeof RangeCommand>) => Promise<RangeResult<unknown>>;
+    /**
+     * Retrieves stats from the index.
+     *
+     * @example
+     * ```js
+     * const statResults = await index.stats();
+     * console.log(statResults); // Outputs the result of the stats operation
+     * ```
+     *
+     * @returns {Promise<RangeReturnResponse<TMetadata>>} A promise that resolves with the response containing the vectorCount, pendingVectorCount, indexSize after the command is executed.
+     */
+    stats: () => Promise<StatsResult>;
 }
 
 /**
@@ -311,4 +329,4 @@ declare class Index extends Index$1 {
     static fromEnv(config?: Omit<IndexConfig, "url" | "token">): Index;
 }
 
-export { type FetchResult, Index, type IndexConfig, type QueryResult, type RangeResult, type Requester, type UpstashRequest, type UpstashResponse, type Vector };
+export { type FetchResult, Index, type IndexConfig, type QueryResult, type RangeResult, type Requester, type StatsResult, type UpstashRequest, type UpstashResponse, type Vector };

package/dist/index.d.ts

@@ -42,7 +42,7 @@ type RequesterConfig = {
     cache?: CacheSetting;
 };
 
-declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range"];
+declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range", "stats"];
 type EndpointVariants = (typeof ENDPOINTS)[number];
 /**
  * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
@@ -63,6 +63,14 @@ declare class DeleteCommand extends Command<{
     constructor(id: (number[] | string[]) | number | string);
 }
 
+type Vector<TMetadata = Record<string, unknown>> = {
+    id: string;
+    vector: number[];
+    metadata?: TMetadata;
+};
+
+type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null;
+
 type QueryCommandPayload = {
     vector: number[];
     topK: number;
@@ -88,14 +96,6 @@ declare class UpsertCommand extends Command<string> {
     constructor(payload: UpsertCommandPayload | UpsertCommandPayload[]);
 }
 
-type Vector<TMetadata> = {
-    id: string;
-    vector: number[];
-    metadata?: TMetadata;
-};
-
-type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null;
-
 type RangeCommandPayload = {
     cursor: number | string;
     limit: number;
@@ -110,6 +110,12 @@ declare class RangeCommand<TMetadata> extends Command<RangeResult<TMetadata>> {
     constructor(payload: RangeCommandPayload);
 }
 
+type StatsResult = {
+    vectorCount: number;
+    pendingVectorCount: number;
+    indexSize: number;
+};
+
 type CommandArgs<TCommand extends new (_args: any) => any> = ConstructorParameters<TCommand>[0];
 /**
  * Serverless vector client for upstash vector db.
@@ -244,6 +250,18 @@ declare class Index$1 {
      * @returns {Promise<RangeReturnResponse<TMetadata>>} A promise that resolves with the response containing the next cursor and an array of vectors, after the command is executed.
      */
     range: (args: CommandArgs<typeof RangeCommand>) => Promise<RangeResult<unknown>>;
+    /**
+     * Retrieves stats from the index.
+     *
+     * @example
+     * ```js
+     * const statResults = await index.stats();
+     * console.log(statResults); // Outputs the result of the stats operation
+     * ```
+     *
+     * @returns {Promise<RangeReturnResponse<TMetadata>>} A promise that resolves with the response containing the vectorCount, pendingVectorCount, indexSize after the command is executed.
+     */
+    stats: () => Promise<StatsResult>;
 }
 
 /**
@@ -311,4 +329,4 @@ declare class Index extends Index$1 {
     static fromEnv(config?: Omit<IndexConfig, "url" | "token">): Index;
 }
 
-export { type FetchResult, Index, type IndexConfig, type QueryResult, type RangeResult, type Requester, type UpstashRequest, type UpstashResponse, type Vector };
+export { type FetchResult, Index, type IndexConfig, type QueryResult, type RangeResult, type Requester, type StatsResult, type UpstashRequest, type UpstashResponse, type Vector };

package/dist/index.js

@@ -1,5 +1,5 @@
 'use strict';
 
-var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var a=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(t=>Math.exp(t)*50)};}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},s=null,f=null;for(let y=0;y<=this.retry.attempts;y++)try{s=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(g){if(this.options.signal?.aborted){let b=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),x={status:200,statusText:this.options.signal.reason??"Aborted"};s=new Response(b,x);break}f=g,await new Promise(b=>setTimeout(b,this.retry.backoff(y)));}if(!s)throw f??new Error("Exhausted all retries");let h=await s.json();if(!s.ok)throw new n(`${h.error}, command was: ${JSON.stringify(e.body)}`);return {result:h.result,error:h.error}}};var r=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t;}async exec(e){let{result:t,error:s}=await e.request({body:this.payload,path:[this.endpoint]});if(s)throw new n(s);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var i=class extends r{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete");}};var p=class extends r{constructor(e){super(e,"query");}};var c=class extends r{constructor(e){super(e,"upsert");}};var l=class extends r{constructor([e,t]){super({ids:e,...t},"fetch");}};var u=class extends r{constructor(e){super(e,"range");}};var m=class extends r{constructor(){super([],"reset");}};var d=class{client;constructor(e){this.client=e;}delete=e=>new i(e).exec(this.client);query=e=>new p(e).exec(this.client);upsert=e=>new c(e).exec(this.client);fetch=(...e)=>new l(e).exec(this.client);reset=()=>new m().exec(this.client);range=e=>new u(e).exec(this.client)};var R=class o extends d{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let t=new a({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(t);}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let s=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new o({...e,url:t,token:s})}};
+var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var a=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(t=>Math.exp(t)*50)};}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},s=null,x=null;for(let f=0;f<=this.retry.attempts;f++)try{s=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(g){if(this.options.signal?.aborted){let b=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),C={status:200,statusText:this.options.signal.reason??"Aborted"};s=new Response(b,C);break}x=g,await new Promise(b=>setTimeout(b,this.retry.backoff(f)));}if(!s)throw x??new Error("Exhausted all retries");let y=await s.json();if(!s.ok)throw new n(`${y.error}, command was: ${JSON.stringify(e.body)}`);return {result:y.result,error:y.error}}};var r=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t;}async exec(e){let{result:t,error:s}=await e.request({body:this.payload,path:[this.endpoint]});if(s)throw new n(s);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var i=class extends r{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete");}};var p=class extends r{constructor(e){super(e,"query");}};var c=class extends r{constructor(e){super(e,"upsert");}};var u=class extends r{constructor([e,t]){super({ids:e,...t},"fetch");}};var l=class extends r{constructor(e){super(e,"range");}};var m=class extends r{constructor(){super([],"reset");}};var d=class extends r{constructor(){super([],"stats");}};var h=class{client;constructor(e){this.client=e;}delete=e=>new i(e).exec(this.client);query=e=>new p(e).exec(this.client);upsert=e=>new c(e).exec(this.client);fetch=(...e)=>new u(e).exec(this.client);reset=()=>new m().exec(this.client);range=e=>new l(e).exec(this.client);stats=()=>new d().exec(this.client)};var R=class o extends h{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let t=new a({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(t);}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let s=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new o({...e,url:t,token:s})}};
 
 exports.Index = R;

package/dist/index.mjs

@@ -1,3 +1,3 @@
-var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var a=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(t=>Math.exp(t)*50)};}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},s=null,f=null;for(let y=0;y<=this.retry.attempts;y++)try{s=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(g){if(this.options.signal?.aborted){let b=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),x={status:200,statusText:this.options.signal.reason??"Aborted"};s=new Response(b,x);break}f=g,await new Promise(b=>setTimeout(b,this.retry.backoff(y)));}if(!s)throw f??new Error("Exhausted all retries");let h=await s.json();if(!s.ok)throw new n(`${h.error}, command was: ${JSON.stringify(e.body)}`);return {result:h.result,error:h.error}}};var r=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t;}async exec(e){let{result:t,error:s}=await e.request({body:this.payload,path:[this.endpoint]});if(s)throw new n(s);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var i=class extends r{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete");}};var p=class extends r{constructor(e){super(e,"query");}};var c=class extends r{constructor(e){super(e,"upsert");}};var l=class extends r{constructor([e,t]){super({ids:e,...t},"fetch");}};var u=class extends r{constructor(e){super(e,"range");}};var m=class extends r{constructor(){super([],"reset");}};var d=class{client;constructor(e){this.client=e;}delete=e=>new i(e).exec(this.client);query=e=>new p(e).exec(this.client);upsert=e=>new c(e).exec(this.client);fetch=(...e)=>new l(e).exec(this.client);reset=()=>new m().exec(this.client);range=e=>new u(e).exec(this.client)};var R=class o extends d{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let t=new a({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(t);}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let s=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new o({...e,url:t,token:s})}};
+var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var a=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(t=>Math.exp(t)*50)};}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},s=null,x=null;for(let f=0;f<=this.retry.attempts;f++)try{s=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(g){if(this.options.signal?.aborted){let b=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),C={status:200,statusText:this.options.signal.reason??"Aborted"};s=new Response(b,C);break}x=g,await new Promise(b=>setTimeout(b,this.retry.backoff(f)));}if(!s)throw x??new Error("Exhausted all retries");let y=await s.json();if(!s.ok)throw new n(`${y.error}, command was: ${JSON.stringify(e.body)}`);return {result:y.result,error:y.error}}};var r=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t;}async exec(e){let{result:t,error:s}=await e.request({body:this.payload,path:[this.endpoint]});if(s)throw new n(s);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var i=class extends r{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete");}};var p=class extends r{constructor(e){super(e,"query");}};var c=class extends r{constructor(e){super(e,"upsert");}};var u=class extends r{constructor([e,t]){super({ids:e,...t},"fetch");}};var l=class extends r{constructor(e){super(e,"range");}};var m=class extends r{constructor(){super([],"reset");}};var d=class extends r{constructor(){super([],"stats");}};var h=class{client;constructor(e){this.client=e;}delete=e=>new i(e).exec(this.client);query=e=>new p(e).exec(this.client);upsert=e=>new c(e).exec(this.client);fetch=(...e)=>new u(e).exec(this.client);reset=()=>new m().exec(this.client);range=e=>new l(e).exec(this.client);stats=()=>new d().exec(this.client)};var R=class o extends h{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let t=new a({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(t);}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let s=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new o({...e,url:t,token:s})}};
 
 export { R as Index };

package/package.json

@@ -1,34 +1 @@
-{
-  "name": "@upstash/vector",
-  "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.",
-  "module": "./dist/index.mjs",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "version": "v0.1.0-alpha-8",
-  "keywords": [
-    "vector",
-    "upstash",
-    "db"
-  ],
-  "author": "Oguzhan Olguncu <oguzhan@upstash.com>",
-  "license": "MIT",
-  "files": [
-    "dist"
-  ],
-  "bugs": {
-    "url": "https://github.com/upstash/vector/issues"
-  },
-  "scripts": {
-    "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts]",
-    "fmt": "bunx biome check --apply ./src",
-    "build": "tsup",
-    "prepare": "husky install"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "@biomejs/biome": "^1.4.1",
-    "bun-types": "latest",
-    "husky": "^8.0.3",
-    "tsup": "latest"
-  }
-}
+{ "name": "@upstash/vector", "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.", "module": "./dist/index.mjs", "main": "./dist/index.js", "types": "./dist/index.d.ts", "version": "v0.1.0-alpha-9", "keywords": [ "vector", "upstash", "db" ], "author": "Oguzhan Olguncu <oguzhan@upstash.com>", "license": "MIT", "files": [ "dist" ], "bugs": { "url": "https://github.com/upstash/vector/issues" }, "scripts": { "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts]", "fmt": "bunx biome check --apply ./src", "build": "tsup", "prepare": "husky install" }, "devDependencies": { "typescript": "^5.0.0", "@biomejs/biome": "^1.4.1", "bun-types": "latest", "husky": "^8.0.3", "tsup": "latest" } }