> For the complete documentation index, see [llms.txt](https://docs.redivis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.redivis.com/api/client-libraries/redivis-js/reference.md).

# Reference

The `redivis` module provides an interface to construct representations of Redivis entities and to create, modify, read, and delete them.

Resources are generally constructed by chaining together multiple constructor methods, reflecting the hierarchical nature of entities in Redivis. For example, to list all variables on a table (which belongs to a dataset in an organization), we would write:

```javascript
import redivis from 'redivis';

const variables = await redivis
  .organization('demo')            // Returns an instance of an Organization
  .dataset('cms_2014_medicare_data') // Returns an instance of a Dataset
  .table('home_health_agencies')   // Returns an instance of a Table
  .listVariables();                // Returns a promise of an array of Variable instances
```

## Interfaces

| Interface                                                                                                | Description                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [**`redivis`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis.md)           | The redivis module. Provides constructor methods for most of the other classes, as well as authentication and configuration.                                                   |
| [**`Dataset`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset.md)           | A Redivis dataset. Provides constructor methods for Tables and Queries scoped to a given dataset, as well as methods for creating, deleting, updating, and releasing datasets. |
| [**`Datasource`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/datasource.md)     | A dataset or workflow that's a source of a workflow.                                                                                                                           |
| [**`Directory`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/directory.md)       | A directory of non-tabular files, built from a file index table.                                                                                                               |
| [**`File`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/file.md)                 | A non-tabular file on Redivis.                                                                                                                                                 |
| [**`Member`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/member.md)             | A member of an organization.                                                                                                                                                   |
| [**`Notebook`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/notebook.md)         | A notebook within a workflow.                                                                                                                                                  |
| [**`Organization`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/organization.md) | A Redivis organization. Provides constructor methods for Datasets, Workflows, Members, and Secrets scoped to a given organization.                                             |
| [**`Parameter`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/parameter.md)       | A parameter within a workflow.                                                                                                                                                 |
| [**`Query`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/query.md)               | A SQL query that references tables on Redivis.                                                                                                                                 |
| [**`ReadStream`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/readstream.md)     | One stream of a parallelized read of a table, query, or upload.                                                                                                                |
| [**`Secret`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/secret.md)             | A secret belonging to a user or organization.                                                                                                                                  |
| [**`Table`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table.md)               | A Redivis table. Numerous methods are available for reading data from the table, as well as uploading data and metadata.                                                       |
| [**`Transform`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/transform.md)       | A transform within a workflow.                                                                                                                                                 |
| [**`Upload`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/upload.md)             | A tabular data upload on a Table.                                                                                                                                              |
| [**`User`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/user.md)                 | A Redivis user. Provides constructor methods for Datasets, Workflows, and Secrets scoped to a given user.                                                                      |
| [**`Variable`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/variable.md)         | A variable (column) of a Table, Query, or Upload.                                                                                                                              |
| [**`Version`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/version.md)           | A version of a Dataset.                                                                                                                                                        |
| [**`Workflow`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/workflow.md)         | A Redivis workflow. Provides constructor methods for Tables, Queries, Transforms, Notebooks, Parameters, and Datasources scoped to a given workflow.                           |

## Conventions

### Arguments

Every method takes its main arguments positionally, followed by an optional object of options. Any positional argument can also be passed by name within the options, so the following are equivalent:

```javascript
await table.toArrowTable(100, { variables: ['name', 'year'] });
await table.toArrowTable({ maxResults: 100, variables: ['name', 'year'] });
```

Unknown options throw a [`ValueError`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.errors.md), rather than being silently ignored.

### Asynchronous methods

Methods that call the Redivis API return promises, and should be `await`ed. Methods that only construct another object (e.g., `dataset.table(name)`) are synchronous, as are methods that return a stream or iterator (e.g., `table.toArrowBatchIterator()`), since these don't make any requests until they are consumed.

### Properties

Each instance has a `properties` attribute, containing the [API resource representation](https://docs.redivis.com/api/resource-definitions/access.md) of the resource. It's populated whenever the resource is fetched (via `get()`), created, updated, or listed. A single property can also be read with `getProperty(name)`, and `JSON.stringify(instance)` serializes its properties.

```javascript
const table = await redivis.table('demo.iris_species.iris').get();
table.properties.numRows; // 150
table.getProperty('numRows'); // 150
```

### Progress and cancellation

Long-running methods (reading data, uploading, downloading, and waiting on jobs) accept an `onProgress` callback, which is called with the progress so far, and an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) as `signal`, which cancels the operation:

```javascript
const controller = new AbortController();
const arrowTable = await table.toArrowTable({
  onProgress: ({ rowsRead, totalRows }) => console.log(`${rowsRead} / ${totalRows}`),
  signal: controller.signal,
});
```

## Environment variables

In Node.js, the following environment variables may be set to modify the behavior of the `redivis` client. Except for `REDIVIS_API_TOKEN`, each can also be set at runtime (in Node.js or the browser) via [`redivis.config()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.config.md), which takes precedence over the environment variable. Options passed directly to a method take precedence over both.

| Environment variable           | `redivis.config()` option                                                                                                        | Default                      |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `REDIVIS_API_TOKEN`            | — (see [`redivis.authorize()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.authorize.md)) |                              |
| `REDIVIS_DEFAULT_WORKFLOW`     | `defaultWorkflow`                                                                                                                |                              |
| `REDIVIS_DEFAULT_DATASET`      | `defaultDataset`                                                                                                                 |                              |
| `REDIVIS_DEFAULT_USER`         | `defaultUser`                                                                                                                    |                              |
| `REDIVIS_DEFAULT_ORGANIZATION` | `defaultOrganization`                                                                                                            |                              |
| `REDIVIS_API_ENDPOINT`         | `apiEndpoint`                                                                                                                    | `https://redivis.com/api/v1` |
| `REDIVIS_CONFIG_DIR`           | `configDir`                                                                                                                      | `~/.redivis`                 |
| `REDIVIS_MAX_PARALLELIZATION`  | `maxParallelization`                                                                                                             | Varies by method             |

#### REDIVIS\_API\_TOKEN

An [API token](https://docs.redivis.com/api/rest-api/authorization.md) to authenticate with, rather than logging in interactively. See [Getting started](https://docs.redivis.com/api/client-libraries/redivis-js/getting-started.md#from-a-long-running-service-api-token).

{% hint style="warning" %}
**Important:** this token acts as a password, and should never be inlined in your code, committed to source control, or otherwise published.
{% endhint %}

#### REDIVIS\_DEFAULT\_WORKFLOW

If set, tables referenced via `redivis.table()` and unqualified table names in `redivis.query()` will be assumed to be within the default workflow, as will parameters, transforms, notebooks, and datasources referenced by name.

Takes the form `owner_name.workflow_name`. [Learn more about referencing resources >](https://docs.redivis.com/api/referencing-resources.md)

#### REDIVIS\_DEFAULT\_DATASET

If set, tables referenced via `redivis.table()` and unqualified table names in `redivis.query()` will be assumed to be within the default dataset.

Takes the form `owner_name.dataset_name`. If both a default dataset and workflow are set, the default workflow will supersede the dataset. [Learn more about referencing resources >](https://docs.redivis.com/api/referencing-resources.md)

#### REDIVIS\_DEFAULT\_USER

If set, datasets and workflows referenced via `redivis.dataset()` and `redivis.workflow()` without an owner (e.g., `redivis.dataset('my_dataset')`) will be assumed to belong to this user.

#### REDIVIS\_DEFAULT\_ORGANIZATION

If set, datasets and workflows referenced without an owner will be assumed to belong to this organization. If both a default user and organization are set, the default user will supersede the organization.

#### REDIVIS\_API\_ENDPOINT

The base URL of the Redivis API. Defaults to `https://redivis.com/api/v1`.

#### REDIVIS\_CONFIG\_DIR

The directory in which credentials are cached after logging in, in Node.js. Defaults to `~/.redivis`. Credentials for redivis.com are cached directly in this directory, and those for any other API endpoint in a subdirectory for its host (e.g., `environments/localhost_8080/`), so that logging in to another environment never replaces your credentials for redivis.com.

#### REDIVIS\_MAX\_PARALLELIZATION

The default for the `maxParallelization` option of methods that read data, upload files, or download files. When not set, each method uses its own default. Reads are always limited to at most 8 parallel streams.

## Data types

When reading data from a table, query, or upload, it is returned as [Apache Arrow](https://arrow.apache.org/docs/js/) data (via [`toArrowTable()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.toarrowtable.md) or [`toArrowBatchIterator()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.toarrowbatchiterator.md)), or as plain JavaScript objects (via [`toRowsArray()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.torowsarray.md)). Each Redivis type is represented as follows:

| Redivis type | Arrow type                                                                                  | toRowsArray() value                                                                |
| ------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `Integer`    | `Int64`                                                                                     | `number` (or `bigint`, with `{ bigInt: true }`)                                    |
| `Float`      | `Float64`                                                                                   | `number`                                                                           |
| `Boolean`    | `Bool`                                                                                      | `boolean`                                                                          |
| `String`     | `Utf8`                                                                                      | `string`                                                                           |
| `Date`       | `DateDay`                                                                                   | `Temporal.PlainDate` (or a `Date` at midnight UTC, with `{ temporal: false }`)     |
| `DateTime`   | `Timestamp` (microseconds)                                                                  | `Temporal.PlainDateTime` (or a `Date` in UTC, with `{ temporal: false }`)          |
| `Time`       | `Time` (microseconds)                                                                       | `Temporal.PlainTime` (or a `HH:MM:SS[.ffffff]` string, with `{ temporal: false }`) |
| `Geography`  | `Utf8` (as [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)) | `string` (as WKT)                                                                  |

Null values are always returned as `null`.

{% hint style="info" %}
JavaScript numbers can only represent integers exactly up to 2<sup>53</sup>. If your data contains larger integers (e.g., IDs), pass `{ bigInt: true }` to `toRowsArray()`, or read the data as an arrow Table, which preserves 64-bit integers.

Similarly, a `Date` only has millisecond precision and is always in UTC, whereas `Temporal` values faithfully represent the microsecond-precision, timezone-less dates and times stored in Redivis. Where [`Temporal`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) isn't built in, the library loads a polyfill, without installing it globally.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.redivis.com/api/client-libraries/redivis-js/reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
