> ## Documentation Index > Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt > Use this file to discover all available pages before exploring further. # GPUdbOptions > GPUdbOptions — Kinetica JavaScript API

Configuration options for GPUdb client.

interface GPUdbOptions {"{"}
client\_name?: string;
client\_version?: string;
encoding?: "binary" | "json";
force\_infinity\_nan\_conversion\_to\_null?: boolean;
getCookie?: () => string | undefined;
ha\_failover\_order?: "sequential" | "random";
headers?: Record\<string, string>;
job\_endpoints?: boolean | string\[];
job\_timeout?: number;
max\_response\_bytes?: number;
oauth\_token?: string;
password?: string;
setCookie?: (cookie: string | undefined) => void;
sync?: boolean;
timeout?: number;
transport?: HttpTransport;
username?: string;
{"}"}
Index

Properties

Optionalclient\_name

client\_name?: string

Name of the calling application, prefixed to the User-Agent header. Node.js only: browsers forbid setting User-Agent.

Optionalclient\_version

client\_version?: string

Version of the calling application; used with client\_name

Optionalencoding

encoding?: "binary" | "json"

How requests and responses are encoded: 'json', the default, or 'binary' for Avro, the encoding the Java and Python APIs use. Also reachable as GPUdb.ENCODING.{"{"}JSON,BINARY{"}"}.

Avro payloads are smaller and quicker to encode and decode, which counts most when inserting and reading records. Under 'binary':

  • Records passed to insert\_records and update\_records are encoded with the table's type. The client looks it up with show\_table on the first insert into each table and caches it; see GPUdb.clear\_type\_cache.
  • Records from get\_records, and the column-major data of execute\_sql, aggregate\_group\_by, aggregate\_unique, aggregate\_unpivot and get\_records\_by\_column, are decoded with the schema the server returns alongside them.
  • Values must match their column types exactly. A number given for a string column, or a record missing a non-nullable column, is rejected with an AvroError naming the field, before anything is sent.
  • A long outside Number's safe-integer range decodes to a bigint, in records and response fields alike, rather than losing precision. Note that JSON.stringify throws on a bigint.
  • Infinity, -Infinity and NaN decode as numbers, where JSON returns them as quoted strings. force\_infinity\_nan\_conversion\_to\_null turns them into null under either encoding.
  • A bytes column decodes to a Uint8Array.
  • Endpoints in JSON\_ONLY\_ENDPOINTS (file transfer, jobs, procs, visualization) stay JSON. So does the record data of get\_records\_by\_series and get\_records\_from\_collection, which travels as JSON inside the Avro envelope.

A custom GPUdbOptions.transport is handed binary request bodies in HttpRequestOptions.bytes rather than body, and must send them unchanged.

Optionalforce\_infinity\_nan\_conversion\_to\_null

force\_infinity\_nan\_conversion\_to\_null?: boolean

Convert the quoted "Infinity", "-Infinity" and "NaN" strings Kinetica returns for those values into null when decoding a payload.

Kinetica sends them quoted, so a double column holding one decodes to the JavaScript string "Infinity" rather than a number. Set this to get null instead. Off by default: the conversion walks every key and value of the payload, which the JavaScript API also considered too expensive to make unconditional.

Equivalent to force\_infinity\_nan\_conversion\_to\_null on the JavaScript API's client, and settable after construction in the same way.

OptionalgetCookie

getCookie?: () => string | undefined

Returns the Cookie header to send with each request. Node.js only: browsers manage cookies themselves and forbid setting the header.

Optionalha\_failover\_order

ha\_failover\_order?: "sequential" | "random"

Order in which clusters are taken from the supplied URL list, for both the initial cluster and the one chosen on failover.

'sequential', the default, uses the caller's order, so the initial cluster is the first URL. 'random' shuffles, randomizing both the initial choice and the failover sequence. Also reachable as GPUdb.HA\_FAILOVER\_ORDER.{"{"}SEQUENTIAL,RANDOM{"}"}.

Optionalheaders

headers?: Record\<string, string>

Custom HTTP headers

Optionaljob\_endpoints

job\_endpoints?: boolean | string\[]

Endpoints to submit through /create/job and poll, rather than calling directly. false, the default, calls every endpoint directly.

A long ALTER can outlast a proxy's idle timeout, and running it as a job keeps the HTTP request short. That only helps where such a proxy exists: a client talking to Kinetica directly pays two extra round trips, and JOB\_POLL\_INTERVAL is 5 s, so an ALTER that finishes in milliseconds either costs one extra request or waits out a full poll interval. Off by default for that reason, and because neither the JavaScript nor the Python API wraps these endpoints -- a client that did so silently would diverge from every other Kinetica API.

true uses GPUdb.DEFAULT\_JOB\_ENDPOINTS. An array names the endpoint paths to wrap, for a deployment whose proxy cuts off other endpoints too.

Set GPUdbOptions.job\_timeout alongside this, or a job that never finishes is polled forever.

Example

``` // Behind a gateway that times out long requests new GPUdb(url, { job_endpoints: true, job_timeout: 300000 }); // A specific set new GPUdb(url, { job_endpoints: ['/alter/table'] }); ```

Optionaljob\_timeout

job\_timeout?: number

How long to keep polling a job-wrapped endpoint, in milliseconds. 0, the default, means no deadline.

timeout bounds each individual HTTP request; it does not bound the polling loop behind /alter/table, which would otherwise wait for a job that never finishes with no way for the caller to give up. This is a separate option rather than an inheritance of timeout because outlasting a per-request timeout is the whole reason those endpoints are wrapped in a job -- an ALTER over a large table is expected to take longer.

On expiry the call rejects. The job itself keeps running on the server.

Optionalmax\_response\_bytes

max\_response\_bytes?: number

Largest response body to accept, in bytes. 0, the default, means no ceiling.

A single unbounded execute\_sql can return more than the process has memory for, and the failure that follows is an out-of-memory kill rather than a caught error. With this set the read is abandoned as soon as the body passes the limit and the call rejects with a ResponseTooLargeError, which names the limit and what was received.

The request is not retried against another URL: an oversized result follows from the query, not from the node that served it.

Optionaloauth\_token

oauth\_token?: string

OAuth2 token for authentication

Optionalpassword

password?: string

Password for authentication

OptionalsetCookie

setCookie?: (cookie: string | undefined) => void

Receives the Set-Cookie header from each response

Optionalsync

sync?: boolean

Block instead of returning a promise when no callback is given, restoring the JavaScript API's synchronous browser behaviour.

Requires a transport with a synchronous mode -- in practice BrowserHttpTransport, which falls back to a blocking XMLHttpRequest. Defaults to false everywhere except the standalone browser build.

Synchronous requests block the UI thread and are deprecated by browsers; treat this as a migration aid, not a long-term setting.

Optionaltimeout

timeout?: number

Request timeout in milliseconds (0 = infinite)

Optionaltransport

transport?: HttpTransport

HTTP transport to use. Defaults to fetch in the browser and the http/https modules under Node.js. Supply one to route requests through a proxy, add instrumentation, or stub the network in tests.

Optionalusername

username?: string

Username for authentication

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.