Records
Last updated
Was this helpful?
Last updated
Was this helpful?
A record object stores no additional data nor has any additional routes beyond those described for all entities and classes. A record object can be used to store data in its details, i.e. as a base object containing only metadata and links to other objects.
/record/new
Creates a new record object. If initializeFrom
is set to a hash specifying a record object, then all metadata fields of the new record created are initialized to be the same as the specified record (with the exception of any other specified fields).
project
string ID of the project or container to which the record should belong (e.g. the string "project-xxxx")
name
string (optional, default is the new ID) The name of the object
tags
array of strings (optional) Tags to associate with the object
types
array of strings (optional) Types to associate with the object; see the page for details on valid input
hidden
boolean (optional, default false) Whether the object should be hidden
properties
mapping (optional) Properties to associate with the object
key Property name
value string Property value
details
mapping or array (optional, default { }) JSON object or array that is to be associated with the object; see the section for details on valid input
folder
string (optional, default "/") Full path of the folder that is to contain the new object
close
boolean (optional, default false) Whether the record should be closed immediately after creation
parents
boolean (optional, default false) Whether all folders in the path provided in folder
should be created if they do not exist
initializeFrom
mapping (optional) Indicate an existing record from which to use the metadata as default values for all fields that are not given:
project
string ID of the project or container containing the record to use
id
string ID of the record to use
nonce
string (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single record is created. For more information, see .
id
string ID of the created record object (i.e. a string in the form "record-xxxx")
InvalidInput
A reserved linking string ("$dnanexus_link") appears as a key in a hash in details
but is not the only key in the hash
A reserved linking string ("$dnanexus_link") appears as the only key in a hash in details
but has value other than a string
The id
given under initializeFrom
is not a valid record ID
For each property key-value pair, the size, encoded in UTF-8, of the property key may not exceed 100 bytes and the property value may not exceed 700 bytes
A nonce
was reused in a request but some of the other inputs had changed signifying a new and different request
A nonce
may not exceed 128 bytes
InvalidType (project
is not a project ID)
PermissionDenied (UPLOAD access required, VIEW access required for the project specified under initializeFrom
if a record was specified)
ResourceNotFound (the specified project is not found, the route in folder
does not exist while parents
is false, or the specified project and/or record ID specified in initializeFrom
are not found)
/record-xxxx/describe
Describes a record. A project ID can be given to request user-provided metadata from a particular project and will be treated as a hint, i.e. if the specified project does not contain the object and another project is found which does contain it and for which the user has VIEW permissions, this other project is used instead to return the metadata. The project ID of the project used to return the user-provided metadata is always returned, regardless of whether it was the same as the hint provided. Details can also be requested via this method, but if the requestor does not have VIEW access, they will not be returned.
project
string (optional) Project or container ID to be used as a hint for finding the object in an accessible project
defaultFields
boolean (optional, default false if fields
is supplied, true otherwise) 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
.
fields
mapping (optional) include or exclude the specified fields from the output. These selections override the settings in defaultFields
.
key Desired output field; see the "Outputs" section below for valid values here
value boolean whether to include the field
The following options are deprecated (and will not be respected if fields
is present):
properties
boolean (optional, default false) Whether the properties should be returned
details
boolean (optional, default false) Whether the details should also be returned
id
string The object ID (i.e. the string "record-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 "record"
types
array of strings Types associated with the object
created
timestamp Time at which this object was created
state
string Either "open" or "closed"
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 object
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 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 present if a job created the object ID of the job that created the object
executable
string present if a job created the object ID of the app or applet that the job was running
The following field (included by default) is available if the object is sponsored by a third party:
sponsoredUntil
timestamp Indicates the expiration time of data sponsorship (this field is only set if the object is currently sponsored, and if set, the specified time is always in the future)
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 Property name
value string Property value
details
mapping or array Contents of the object’s details
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, or the value of properties
(if supplied) is not a boolean)
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))
Alternatively, you can use the method to describe a large number of data objects at once.