# Databases

The database data object represents a Parquet-format database in the platform. In Spark SQL, you can use either the shorter `databaseName` or the longer `uniqueDatabaseName` for cases with potential duplicates. You can store additional database metadata in properties.

## Database API Method Specifications

### API method: `/database-xxxx/describe`

#### Specification

Describes a database data object. A project ID can be given to request user-provided metadata from a particular project but it is not necessary as database data object belongs only to one project always. Cloning of database data object is suppressed. A relocate method is available for moving a database data object from one project to another.

#### Inputs

* `project` **string** (optional) Project or container ID to be used as a hint for finding the object in an accessible project.
* `defaultFields` **boolean** (optional) Whether to include the default set of fields in the output (the default fields are described in the "Outputs" section below). The selections are overridden by any fields explicitly named in `fields`.
  * Defaults to `false` if `fields` is supplied, `true` otherwise.
* `fields` **mapping** (optional) Include or exclude the specified fields from the output. These selections override the settings in `defaultFields`.
  * **key** — the desired output field. See "Outputs" below for valid values.
  * **value** **boolean** — whether to include the field.

The following options are deprecated (and are not respected if `fields` is present):

* `properties` **boolean** (optional, deprecated) Whether the properties should be returned. Defaults to `false`.
* `details` **boolean** (optional, deprecated) Whether the details should also be returned. Defaults to `false`.

#### Outputs

* `id` **string** The object ID, such as "database-xxxx".

The following fields are included by default (but can be disabled using `fields` or `defaultFields`):

* `project` **string** ID of the project or container in which the object was found.
* `class` **string** The value "database".
* `databaseName` **string** The suffix of `uniqueDatabaseName` used for referencing a Parquet-format database. If a user has access to multiple databases with the same `databaseName`, the user has to reference the Parquet-format database by `uniqueDatabaseName`.
* `uniqueDatabaseName` **string** The Parquet-format database name.
* `types` **array of strings** Types associated with the object.
* `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this object was created.
* `state` **string** Always "open".
* `hidden` **boolean** Whether the object is hidden or not.
* `links` **array of strings** The object IDs that are pointed to from this object.
* `name` **string** The name of the database data object. The `name` of the object can be different from `databaseName`.
* `folder` **string** The full path to the folder containing the object.
* `sponsored` **boolean** Whether the object is sponsored by DNAnexus.
* `tags` **array of strings** Tags associated with the object.
* `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which the user-provided metadata of the object was last modified.
* `createdBy` **mapping** How the object was created.
  * `user` **string** ID of the user who created the object or launched an execution which created the object.
  * `job` **string** ID of the job that created the object.
    * Only present when a job created the object.
  * `executable` **string** ID of the app or applet that the job was running.
    * Only present when a job created the object.

The following field (included by default) is available if the object is sponsored by a third party:

* `sponsoredUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Indicates the expiration time of data sponsorship. This field exists only for sponsored objects and specifies a future timestamp.

The following fields are only returned if the corresponding field in the `fields` input is set to `true`:

* `properties` **mapping** Properties associated with the object.
  * **key** — the property name.
  * **value** **string** — the property value.
* `details` **mapping or array** Contents of the object's details.

#### Errors

* ResourceNotFound
  * The specified object does not exist or the specified `project` does not exist
* InvalidInput
  * The input is not a hash, `project` (if supplied) is not a string
* PermissionDenied
  * VIEW access required for the `project` provided (if any), and VIEW access required for **some** project containing the specified object (not necessarily the same as the hint provided)

### API method: `/database-xxxx/relocate`

#### Specification

Moves the database data object from the current project to the specified project. You may not move a database to another project which already contains a database with the same database name.

#### Inputs

* `project` **string** (required) ID of the project to which the database should be relocated, such as "project-xxxx".
* `destination` **string** (optional) The destination folder in `project`. Defaults to `"/"`.
* `parents` **boolean** (optional) Whether the destination folder and/or parent folders should be created if they do not exist. Defaults to `false`.

#### Outputs

* `id` **string** ID of the moved database object, such as "database-xxxx".
* `project` **string** ID of the modified destination project.

#### Errors

* ResourceNotFound
  * The specified database does not exist
  * The project specified in `project` does not exist
  * The folder specified in `destination` does not exist in the destination project and `parents` is set to false
  * The source or destination project is not accessible for specified action due to missing license
* InvalidInput
  * `project` is missing, is not a project ID or is the same as source project
  * `destination` (if provided) is not a nonempty string starting with "/"
  * `parents` (if provided) is not a boolean
  * `project` must be in the same region as the source project
  * A database with the same `databaseName` already exists in the target project
* PermissionDenied
  * CONTRIBUTE/ADMINISTER access is required, depending on PROTECTED flag on the source project
  * UPLOAD access is required in the destination project