ecl-logo Documentation

Download

Download[objects]packets

download the objects.

Download[objects, fields]values

downloads only the specified fields of the objects.

Download[objects, fieldLists]values

downloads the sub-list of fields from fieldLists for each of objects at the same position in the list.

Download[references]values

downloads the values from the fields in the given field references.

Details

  • Downloading from a packet, instead of an object, will not fetch any new data from the server and will instead lookup values in that packet.
  • Downloading a _Packet head and a sequence of fields, instead of a list of fields, will cause a partial packet of values to be returned.
  • When the PaginationLength option is specifed and a multiple field has a length greater then that number, the resulting key-value pair is a RuleDelayed call to Download.
  • Downloading Null at any index will return Null for that index.
  • Downloading $Failed at any index will return $Failed for all fields at that index.
  • Download can traverse links using a special syntax: ProtocolsAuthored[Status] will download the Status field from all the objects linked in the ProtocolsAuthored field.
  • Download can extract a specific index from an indexed multiple field: StatusLog[[All,2]] will Download all values at index 2 in an indexed multiple field.
  • The above can be combined to an arbitrary depth, for example: ProtocolsAuthored[Resources][[All,1]][Model]
  • If a Null value is encountered at any point in the link traversal, it will stop and return Null for that node.
  • Using the special field "All" will download all the fields in the related packet (for example, Model[All]).
  • All must be the last field requested in a change, it cannot be used in the middle of a traversal (Model[All][Name] is invalid).
  • The part syntax Contents[[2]] & Contents[[All,2]] are equivalent.
  • $CacheSize controls the maximum size (in bytes) of previously downloaded objects which will be cached.
  • Input
    Output
    General Options
    Attributes
  • HoldRest
  • Messages
  • BadCachePackets at positions `1` in the explicit cache do not have object keys, and have been ignored. Please check your syntax and try again.
    BigDataFieldThere was an error with big data field `1`: `2`. Please update your download request and try again.
    CloudFileThere was a problem downloading a cloudfile. Please try again.
    CloudFileMetadataThere was a problem downloading the metadata for a cloudfile. Please try again.
    CycleCycles detected when downloading the repeated fields `1` for objects `2`. Please update your download request and try again.
    DateMismatchThe provided dates do not match the given input. Either provide a single date to map across every input, or provide a list of dates that match the number of objects in the input.
    DatePrecedeCreationTimeThe provided date is before the object creation date. Please verify timestamp does not precede creation time for object.
    DateTooFarInFutureThe provided date is too far in the future. Please update your download request and try again.
    FieldDefinitionMismatchField definition of field `1` for object `2` in SLL does not match it's definition in constellation. Download response for this field might be incomplete or wrong. Please make sure the relevant field is SyncType'd correctly
    FieldDoesntExistCould not find the field(s) `1` in object(s) `2`. Please check your spelling and try again.
    FieldTooLargeThe field(s) `1` in objects(s) `2` are too large and cannot be downloaded directly into the notebook. Please update your download and try again.
    FileSystemsPermissionsErrorThere was a problem accessing the file system at path `1`. Please make sure that path is accessible to Command Center and try again.
    InternalErrorAn internal error occurred in the Telescope App. Please file a troubleshooting report. `1`
    InvalidBigQuantityArrayByteLimitThe value `1` for BigQuantityArrayByteLimit is invalid. Please enter an integer and try again.
    InvalidFieldField specifications `1` are invalid. Please correct them and try again.
    InvalidOptionThere was an invalid value `1` passed to the option `2`. Please update your request and try again.
    InvalidSearchSearch conditions `1` were provided for downloading fields `2` but are invalid. Must be an expression of And, Or, Greater, Less, LessEqual, GreaterEqual, NotEqual, or Equal and not contain any quantities.
    LengthCannot download Length of fields `1` from objects `2` because they are not multiple fields.
    MapThreadThe provided lengths of `1` (`2`) and `3` (`4`) are unequal. Please correct them and try again.
    MismatchedTypeIds `1` exist in the database, but are not of types `2`. Please update your download request and try again.
    MissingCacheFieldCould not find the field(s) `1` in the cache packets for object(s) `2`. Please check your spelling and try again.
    MissingFieldCould not find the field(s) `1` in the packets for object(s) `2`. Please check your spelling and try again.
    MissingObjectKeywordThe specified Download is missing Object keyword. Please update your download request and try again.
    NetworkErrorThe specified Download call failed due to a network error: `1`. Please check your internet connection and try again.
    NotLinkFieldCould not Download fields `1` because `2` are not link fields. Please update your download request and try again.
    ObjectDoesNotExistThe following objects could not be found: `1`. Please check confirm these objects exist or if you have access to these objects.
    PacketLengthCannot download Length inside Packet fields `1`. Please update your download request and try again.
    PacketWrapperMultipleObjectsThe Packet wrapper is used for more than one through-link traversal with through-links for `1`. Please separate these into several uses of the Packet wrapper around each traversal separately.
    PartParts `1` of fields `2` do not exist for objects `3`. Please check your syntax and try again.
    RedundantFieldFields `1` are equivalent to Packet[All]. Please consider updating your download request.
    TimeoutThe Constellation request did not finish computing in `1` minutes and was aborted due to timeout. Please contact the platform team, and in the meantime try to partition and send your request in smaller chunks
    TransientNetworkErrorThere was a problem communicating with constellation. Please check your network connection and run your code again.
    UnknownTypeTypes `1` are not defined. Please check your spelling and try again.
    UnparsableDownloadErrorThere was a problem parsing your download request. Please check the syntax of your request and try again.
    UnusedSearchConditionsSearch conditions `1` were provided for downloading fields `2`, but these fields are not Repeated and thus search conditions are irrelevant.

Examples

Basic Examples  (3)

Downloading a Link returns the packet for the object the link points to:

Downloading an object returns an object packet:

Download only a sub-set of fields from an object:

Additional Examples  (61)

Download a field through a link:

Download a field through a link and another field at the same time:

Download a set of fields from a list of objects and/or links:

Download with Time respects Timeless Objects. (Historical value was 1 degree):

Download with Time respects Timeless Object through a Link. (Historical value was 1 degree):

Field  (1)

Download through links using the Field syntax:

Field Reference  (4)

Download a list of field references:

Downloading a field reference to a specific index only returns items at that index:

Downloading a field reference to a specific named column only returns items at that index:

Download the Name of an object from a field reference:

Fields  (1)

Any fields which are not set will be either Null (single fields) or {} (multiple fields):

Length  (3)

Download the length of a multiple field without using the Download symbol:

Download the length of a Repeated traversal:

Length fields can contain subsequent fields, but only the length of the first field is returned:

Named Fields  (2)

Download a named multiple field:

Download a named single field:

Names  (1)

Download an object using its name:

Nested Lists  (5)

Download a field from a nested list of objects:

Download multiple lists of fields from one object:

Download the same set of fields for each object in a nested list:

For each object, Download a list of fields:

For each object in a list of objects, Download the corresponding list of fields:

Null  (5)

Downloading a list of fields from a list of objects where some indices are Null returns Null for those indices:

Downloading a list of fields from Null returns Null:

Downloading a list of objects where some indices are Null returns Null for those indices:

Downloading Null returns Null:

With _Packet, Downloading a list of fields from a list of objects where some indices are Null returns Null for those indices:

Packet  (12)

Download fields into a Packet :

Downloading additional fields from Repeated using Packet returns a packet for each set of fields:

Downloading a List[List[objects]] with a List[List[___Packet]] of fields works:

Downloading a List[objects] with a List[List[___Packet]] of fields works:

Downloading a list of both fields and Packets of fields works:

Downloading one object with a List[List[___Packet]] of fields works:

Downloading using Repeated & Packet returns a packet at each level:

Downloading with a list of fields and Packets of fields, returns a list of some packets and some values:

Downloading with a list of Packet of fields, for a list of lists of objects, works (depth: 2,2):

Downloading with a list of Packets of fields, instead of a list of lists of fields, returns a list of packets:

Downloading with an empty Packet of fields returns a packet of default fields:

Download through links and get back a packet with the specified fields:

Packets  (2)

Downloading a packet returns the packet untouched:

Downloading a specific field from a packet extracts that field:

Repeated  (2)

Downloading a repeated field MyField.. returns each MyField available through repeated MyField references, until an object does not contain MyField:

Downloading a repeated field MyFields.. returns $Failed each time a type does not contain the required field:

ReplaceAll  (1)

Use /. to download field values from a list of objects:

Search Conditions  (3)

None must be used as a placeholder when recursively downloading some fields with search conditions but not others:

Recursively download a link field while a search condition remains True:

Use search conditions when downloading different fields from different objects:

Structured Lists  (1)

Download will preserve the structure of nested Lists:

SubValues  (3)

Download a field from a list of object references:

Download a field from an object without using the Download symbol:

Download multiple fields from an object without using the Download symbol:

Traversal  (3)

Multiple keys can be downloaded from named fields:

Named columns can be downloaded from fields that are Multiple:

Named rows can be downloaded from fields that are Single:

VariableUnit  (2)

Quantities in VariableUnit fields will be downloaded in the original units (from cache packets):

Quantities in VariableUnit fields will be downloaded in the original units (which were uploaded with):

$CacheSize  (1)

Limit the amount of data (in bytes) that will be cached by setting $CacheSize:

$Failed  (4)

Downloading a list of fields from $Failed returns $Failed for each field:

Downloading a list of fields with a Packet from $Failed returns $Failed:

Downloading a list of object references where some are $Failed returns $Failed for each field:

Downloading $Failed returns $Failed:

Options  (15)

BigQuantityArrayByteLimit  (1)

A byte limit can be set to prevent download quantity Arrays over a particular size:

Cache  (6)

Cache->Automatic uses the value of Cache in the type definition for each object:

Cache->packets will go to the server for fields missing in a packet provided via the option but still throw messages:

Cache->packets will use historic values provided by the packets:

Cache->packets will use the values in the packets, providing messages for any missing keys, when given a list of FieldReferences:

Cache->Session forces subsequent Download calls to refer to the local cache without checking the server for changes:

Test - Cache->Download always checks the server for the latest version of the object regardless the object was cached with Session:

Date  (3)

A list of dates threads across a list of objects:

Date Option allows the user to download an Object as it looked at a specific time. Note a single date can apply across a list of objects:

Whenever a Temporal Link is Downloaded, the Cache option is ignored and the values are downloaded directly from the Database:

HaltingCondition  (1)

HaltingCondition->Inclusive includes the final object that failed the search condition in a recursive download:

IgnoreTime  (2)

Download with Date option and with IgnoreTime option specified:

Download with Date option and with IgnoreTime option specified:

PaginationLength  (1)

If a multiple field is longer than the PaginationLength it will be returned as a RuleDelayed:

SquashResponses  (1)

SquashResponses->False uses deprecated Download logic for reduced performance:

Attributes  (2)

HoldRest  (2)

A symbol with values will be evaluated automatically (without the use of Evaluate):

The field arguments to Download are held so Evaluate must be used to force evaluation if necessary:

Messages  (26)

BadCache  (1)

Cache->packets removes everything that does not have a valid object key from the packets list, and provides a warning for any non null ignored elements:

Cycle  (1)

Recursively downloading a field which results in a cycle stops when it reaches a previously traversed element and throws a message:

DateMismatch  (1)

Fail if provided dates cannot thread with the provided objects:

DatePrecedeCreationTime  (1)

When Object of invalid date is downloaded, DatePrecedeCreationTime message is thrown and $Failed is returned:

FieldDoesntExist  (1)

Downloading a field that does not exist in a type returns $Failed:

FieldTooLarge  (1)

If a bigQAField is too large, it won't get downloaded:

InvalidField  (2)

Field sequence with nonsense inputs throws an error:

Returns $Failed for each field in each object and throws a message if input fields are not symbols or valid link traversal expressions when specified in nested lists:

InvalidSearch  (1)

Returns $Failed and throws a message if search conditions are not properly formatted:

Length  (1)

Cannot Download Length from a single field:

MapThread  (1)

Returns $Failed and throws a message if search conditions do not match the length of fields:

MismatchedType  (1)

Downloading an object whose id exists in the database with a different type, fails and provides a message:

MissingCacheField  (1)

Downloading a field from an object specified via that Cache option which is missing that field goes to the server to get the value but also throws a warning:

MissingField  (1)

When Downloading a specific field from a packet that is missing from the packet, returns $Failed and a warning message:

NetworkError  (1)

Returns $Failed and throws a message if there is an error communicating with the ECL servers:

NotLinkField  (2)

All cannot be the first symbol in a Field:

Cannot download through links for fields which are not links:

NotLoggedIn  (1)

Returns $Failed and throws a NotLoggedIn message if not logged in:

ObjectDoesNotExist  (2)

When Object id does not exist, the ObjectDoesNotExist message is thrown and $Failed is returned:

When Object Name does not exist, the ObjectDoesNotExist message is thrown and $Failed is returned:

PacketLength  (1)

Returns $Failed and provides a message when trying to coerce a Length into a Packet:

PacketWrapperMultipleObjects  (1)

When using the Packet syntax, cannot download through multiple links in the same Packet:

Part  (1)

Return $Failed and provide a message when an out of bounds part is is requested from a field:

RedundantField  (1)

Downloading Packet[All, Field] provides a packet with all fields populated, and warns that Field is redundant:

UnknownType  (1)

Nonexistant type returns $Failed and provides an error:

UnusedSearchConditions  (1)

A warning will be thrown if search conditions are specified for a non-recursive download:

Last modified on Thu 29 Jun 2023 16:41:28