> 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/table.md).

# Table

Work with tables on Redivis

## *class* <mark style="color:purple;">Table</mark>

Tables are the fundamental data-containing entity in Redivis. Tables belong to either a dataset or workflow, and are made up of rows and variables (columns). Various methods allow you to read table data, as well as to create / update / delete tables belonging to an unreleased version of a dataset.

Certain tables may be [file index tables](https://docs.redivis.com/reference/datasets/files#folders-and-index-tables), which represent a collection of non-tabular files, where each row corresponds to a file. There are additional methods available on file index tables that allow for you to interface with these files.

## Constructors

| Method                                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**`redivis.table`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.table.md)(name\[, options])                    | Return a Table within the [current default scope](https://docs.redivis.com/api/client-libraries/redivis-js/reference.md#environment-variables) (either a dataset or workflow). If no default scope is specified, the name must be fully qualified (e.g., `demo.iris_species.iris`). Consult the [referencing resources](https://docs.redivis.com/api/referencing-resources.md) documentation to learn more. |
| [**`Dataset.table`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.table.md)(name)                                | Return a Table within a specific [dataset](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset.md). The name does not need to be fully qualified, since the table lookup is already scoped to a dataset.                                                                                                                                                                             |
| [**`Workflow.table`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/workflow/workflow.table.md)(name)                             | Return a Table within a specific [workflow](https://docs.redivis.com/api/client-libraries/redivis-js/reference/workflow.md). The name does not need to be fully qualified, since the table lookup is already scoped to a workflow.                                                                                                                                                                          |
| [**`Dataset.listTables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.listtables.md)(\[maxResults])             | Returns a list of Tables within a dataset.                                                                                                                                                                                                                                                                                                                                                                  |
| [**`Workflow.listTables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/workflow/workflow.listtables.md)(\[maxResults, options]) | Returns a list of Tables within a workflow.                                                                                                                                                                                                                                                                                                                                                                 |

## Examples

{% tabs %}
{% tab title="Basics" %}

```javascript
const table = redivis.table('demo.iris_species.iris'); // owner.dataset|workflow.table

await table.exists(); // -> true
await table.get(); // table.properties is now populated with the table resource definition

table.variable('SepalLengthCm'); // -> Returns a Variable
await table.toRowsArray(); // -> Returns an array of row objects
await table.file('filename.png'); // -> Returns a File in a file index table
```

{% endtab %}

{% tab title="Read tabular data" %}

```javascript
// Can also do: redivis.table('demo.iris_species.iris')
const dataset = redivis.organization('demo').dataset('iris_species');
const table = dataset.table('iris');

const rows = await table.toRowsArray();
// [
//   { Id: 33, SepalLengthCm: 5.2, SepalWidthCm: 4.1, PetalLengthCm: 1.5, PetalWidthCm: 0.1, Species: 'Iris-setosa' },
//   ...
// ]

// Other methods to read data:
// await table.toArrowTable()
// table.toArrowBatchIterator()
// await table.toReadStreams()
```

{% endtab %}

{% tab title="Read files" %}

```javascript
// See https://redivis.com/datasets/yz1s-d09009dbb/files for example data
const table = redivis.table('demo.example_data_files:yz1s:v1_3.example_file_types:4c10');
const textFile = await table.file('pandas_core.py');
const imageFile = await table.file('bogota.tiff');

// Read file contents
const text = await textFile.read({ asText: true });
const bytes = await imageFile.read(); // A Uint8Array

// Stream the file's contents
const stream = imageFile.stream(); // A ReadableStream

// Download the file (Node.js only)
await imageFile.download('./path/'); // Downloaded as ./path/bogota.tiff
await textFile.download('./path/renamed.txt'); // Downloaded as ./path/renamed.txt
```

{% endtab %}

{% tab title="Create a table" %}

```javascript
let dataset = redivis.user('user_or_organization_name').dataset('my_dataset');

// Tables can only be created on an unreleased version.
// If necessary, create a new version:
// dataset = await dataset.createNextVersion();

const table = await dataset.table('my_new_table').create({ description: 'some description' });

// Learn more about uploading data in the Upload documentation
await table.upload('data.csv').create(file);
```

{% endtab %}

{% tab title="List variables" %}

```javascript
const table = redivis.organization('demo').dataset('iris_species').table('iris');

for (const variable of await table.listVariables()) {
  console.log(variable.properties);
}
```

{% endtab %}
{% endtabs %}

## Attributes

| Name                     | Description                                                                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`dataset`**            | A reference to the [Dataset](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset.md) that the table belongs to. Will be `undefined` if the table belongs to a workflow.                                                                                   |
| **`workflow`**           | A reference to the [Workflow](https://docs.redivis.com/api/client-libraries/redivis-js/reference/workflow.md) that the table belongs to. Will be `undefined` if the table belongs to a dataset.                                                                                  |
| **`name`**               | The table's name.                                                                                                                                                                                                                                                                |
| **`properties`**         | An object containing the [API resource representation of the table](https://docs.redivis.com/api/resource-definitions/table.md#base-definition). This will only be populated after certain methods are called, particularly the `get` method, and will otherwise be `undefined`. |
| **`qualifiedReference`** | The [fully qualified reference](https://docs.redivis.com/api/referencing-resources.md) to this table, for use (e.g.) in a SQL query. For example, `demo.reddit:prpw:v1_0.posts:7q4m`                                                                                             |
| **`scopedReference`**    | The canonical reference for the table, without any qualifiers. E.g., `posts:7q4m`                                                                                                                                                                                                |

## Methods

| Method                                                                                                                                                             | Description                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reading data and metadata**                                                                                                                                      |                                                                                                                                                                                                 |
| [**`Table.download`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.download.md)(\[path, options])                               | Export the table in a particular format and download it to disk (Node.js only).                                                                                                                 |
| [**`Table.exists`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.exists.md)()                                                   | Check whether the table exists.                                                                                                                                                                 |
| [**`Table.file`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.file.md)(path)                                                   | Return a [File](https://docs.redivis.com/api/client-libraries/redivis-js/reference/file.md) within a file index table.                                                                          |
| [**`Table.get`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.get.md)()                                                         | Fetch table metadata. Once called, the `properties` attribute on the table will be fully populated.                                                                                             |
| [**`Table.listFiles`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.listfiles.md)(\[maxResults, options])                       | Return a list of [File](https://docs.redivis.com/api/client-libraries/redivis-js/reference/file.md) instances in a file index table.                                                            |
| [**`Table.listVariables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.listvariables.md)(\[maxResults])                        | Return a list of [Variable](https://docs.redivis.com/api/client-libraries/redivis-js/reference/variable.md) instances associated with this table.                                               |
| [**`Table.toArrowBatchIterator`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.toarrowbatchiterator.md)(\[maxResults, options]) | Return an async iterator of arrow [RecordBatches](https://arrow.apache.org/docs/js/classes/Arrow_dom.RecordBatch.html), for processing the table's data in a memory-efficient streaming manner. |
| [**`Table.toArrowTable`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.toarrowtable.md)(\[maxResults, options])                 | Return an arrow [Table](https://arrow.apache.org/docs/js/classes/Arrow_dom.Table.html) with the table's data.                                                                                   |
| [**`Table.toDirectory`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.todirectory.md)(\[options])                               | Return a [Directory](https://docs.redivis.com/api/client-libraries/redivis-js/reference/directory.md) of the files in a file index table.                                                       |
| [**`Table.toReadStreams`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.toreadstreams.md)(\[targetCount, options])              | Return a list of [ReadStreams](https://docs.redivis.com/api/client-libraries/redivis-js/reference/readstream.md), for reading the table in parallel.                                            |
| [**`Table.toRowsArray`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.torowsarray.md)(\[maxResults, options])                   | Return an array of row objects with the table's data.                                                                                                                                           |
| [**`Table.updateVariables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.updatevariables.md)(variables)                        | Batch update variable metadata on the table.                                                                                                                                                    |
| [**`Table.variable`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.variable.md)(name)                                           | Return a [Variable](https://docs.redivis.com/api/client-libraries/redivis-js/reference/variable.md) within the table.                                                                           |
| **Uploading and modifying data**                                                                                                                                   |                                                                                                                                                                                                 |
| [**`Table.addFiles`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.addfiles.md)(options)                                        | Upload non-tabular files to an unreleased file index table.                                                                                                                                     |
| [**`Table.create`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.create.md)(\[options])                                         | Create a table within an unreleased version of a dataset.                                                                                                                                       |
| [**`Table.delete`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.delete.md)()                                                   | Delete a table belonging to an unreleased version of a dataset.                                                                                                                                 |
| [**`Table.listUploads`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.listuploads.md)(\[maxResults])                            | Return a list of [Uploads](https://docs.redivis.com/api/client-libraries/redivis-js/reference/upload.md) on the table.                                                                          |
| [**`Table.update`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.update.md)(options)                                            | Update properties on the table (name, description, uploadMergeStrategy).                                                                                                                        |
| [**`Table.upload`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table/table.upload.md)(\[name])                                            | Return an [Upload](https://docs.redivis.com/api/client-libraries/redivis-js/reference/upload.md) on the table, which can subsequently be used to upload tabular data.                           |


---

# 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/table.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.
