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

# Dataset

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

Datasets are a core entity on Redivis, and all data uploaded to Redivis must belong to a dataset. Datasets are owned by a user or organization, and contain one or more tables, organized into versions. Various methods allow you to construct the tables and queries within a dataset, as well as to create, update, version, and release datasets.

## Constructors

| Method                                                                                                                                                                  | Description                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**`redivis.dataset`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.dataset.md)(name\[, options])                                | Return a Dataset, given its qualified reference (e.g., `demo.iris_species`), or its name within the [default user or organization](https://docs.redivis.com/api/client-libraries/redivis-js/reference.md#environment-variables). |
| [**`Organization.dataset`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/organization/organization.dataset.md)(name\[, options])                 | Return a Dataset owned by an [organization](https://docs.redivis.com/api/client-libraries/redivis-js/reference/organization.md).                                                                                                 |
| [**`User.dataset`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/user/user.dataset.md)(name\[, options])                                         | Return a Dataset owned by a [user](https://docs.redivis.com/api/client-libraries/redivis-js/reference/user.md).                                                                                                                  |
| [**`Organization.listDatasets`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/organization/organization.listdatasets.md)(\[maxResults, options]) | List the Datasets owned by an organization.                                                                                                                                                                                      |
| [**`User.listDatasets`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/user/user.listdatasets.md)(\[maxResults])                                  | List the Datasets owned by a user.                                                                                                                                                                                               |

The dataset's name may include a reference id and version tag, following the [resource reference syntax](https://docs.redivis.com/api/referencing-resources.md) (e.g., `us_forest_service_fires:5k9t:v1_1`). The version can also be provided via the `version` option (e.g., `{ version: 'next' }`). If no version is specified, the dataset refers to its current (latest released) version.

## Examples

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

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

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

dataset.table('iris'); // -> Returns a Table
dataset.query('SELECT * FROM iris'); // -> Returns a Query, scoped to the dataset
await dataset.listTables(); // -> Returns an array of Tables
```

{% endtab %}

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

```javascript
// Could also create a dataset under an organization:
// const dataset = redivis.organization('my_organization').dataset('some_dataset');
const dataset = redivis.user('your_username').dataset('some_dataset');

// publicAccessLevel can be one of 'none', 'overview', 'metadata', 'sample', 'data'
await dataset.create({ publicAccessLevel: 'overview', description: 'Some description' });
```

{% endtab %}

{% tab title="Create a new version" %}

```javascript
const dataset = redivis.user('your_username').dataset('some_dataset');

// Returns the dataset at its next version, creating it unless it already exists
const nextVersion = await dataset.createNextVersion({ ifNotExists: true });

await nextVersion.table('my_table').upload().create('./data.csv');

await nextVersion.release({ releaseNotes: 'Added data for 2024' });
```

{% endtab %}

{% tab title="Update metadata" %}

```javascript
const dataset = redivis.user('your_username').dataset('some_dataset');

await dataset.update({
  description: 'A dataset of things',
  labelsToAdd: ['climate'],
  tagsToRemove: ['draft'],
});
```

{% endtab %}
{% endtabs %}

## Attributes

| Name                     | Description                                                                                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`name`**               | The dataset's name.                                                                                                                                                                                                                                                  |
| **`organization`**       | A reference to the [Organization](https://docs.redivis.com/api/client-libraries/redivis-js/reference/organization.md) that owns the dataset. Will be `undefined` if the dataset is owned by a user.                                                                  |
| **`user`**               | A reference to the [User](https://docs.redivis.com/api/client-libraries/redivis-js/reference/user.md) that owns the dataset. Will be `undefined` if the dataset is owned by an organization.                                                                         |
| **`versionTag`**         | The tag of the version that the dataset refers to (e.g., `v1_0`, or `next`), if one was specified or the dataset has been fetched.                                                                                                                                   |
| **`properties`**         | An object containing the [API resource representation of the dataset](https://docs.redivis.com/api/resource-definitions/dataset.md). 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 dataset, e.g. `demo.us_forest_service_fires:5k9t:v1_1`                                                                                                                |
| **`scopedReference`**    | The canonical reference for the dataset, without its owner, e.g. `us_forest_service_fires:5k9t:v1_1`                                                                                                                                                                 |

## Methods

| Method                                                                                                                                                 | Description                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| [**`Dataset.create`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.create.md)(\[options])                       | Create a new dataset.                                                                                                |
| [**`Dataset.createNextVersion`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.createnextversion.md)(\[options]) | Create the next (unreleased) version of the dataset, and return the dataset at that version.                         |
| [**`Dataset.delete`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.delete.md)()                                 | Delete the dataset.                                                                                                  |
| [**`Dataset.exists`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.exists.md)()                                 | Check whether the dataset exists.                                                                                    |
| [**`Dataset.get`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.get.md)()                                       | Fetch the dataset's metadata, populating `dataset.properties`.                                                       |
| [**`Dataset.listTables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.listtables.md)(\[maxResults])            | List the dataset's [Tables](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table.md).            |
| [**`Dataset.listVersions`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.listversions.md)(\[maxResults])        | List the dataset's [Versions](https://docs.redivis.com/api/client-libraries/redivis-js/reference/version.md).        |
| [**`Dataset.nextVersion`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.nextversion.md)()                       | Return the dataset at the version after this one, if any.                                                            |
| [**`Dataset.previousVersion`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.previousversion.md)()               | Return the dataset at the version before this one, if any.                                                           |
| [**`Dataset.query`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.query.md)(query)                              | Return a [Query](https://docs.redivis.com/api/client-libraries/redivis-js/reference/query.md) scoped to the dataset. |
| [**`Dataset.release`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.release.md)(\[options])                     | Release the next version of the dataset.                                                                             |
| [**`Dataset.table`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.table.md)(name)                               | Return a [Table](https://docs.redivis.com/api/client-libraries/redivis-js/reference/table.md) within the dataset.    |
| [**`Dataset.unrelease`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.unrelease.md)()                           | Unrelease the current version of the dataset.                                                                        |
| [**`Dataset.update`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.update.md)(options)                          | Update the dataset's metadata.                                                                                       |
| [**`Dataset.updateVariables`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.updatevariables.md)(variables)      | Batch update variable metadata across the dataset's tables.                                                          |
| [**`Dataset.version`**](https://docs.redivis.com/api/client-libraries/redivis-js/reference/dataset/dataset.version.md)(\[tag])                         | Return a [Version](https://docs.redivis.com/api/client-libraries/redivis-js/reference/version.md) of the dataset.    |


---

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