X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/e0903a2cff2df4e6169e95f7439c0fa361c60ea8..a3da6f03cfb1bd6b36fdb1a51efeafcd7d64157e:/doc/api/methods.html.textile.liquid diff --git a/doc/api/methods.html.textile.liquid b/doc/api/methods.html.textile.liquid index 5b35c16a81..00c120d9f8 100644 --- a/doc/api/methods.html.textile.liquid +++ b/doc/api/methods.html.textile.liquid @@ -5,24 +5,37 @@ navmenu: Concepts title: Common resource methods ... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. + +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} The following methods are available for most resources. Some resources may limit who can perform certain operations. Consult documentation for individual resource types for details. -The methods are relative to the base URI, e.g. @/arvados/v1/resource_type@. For arguments specifying a *Location* of @path@, the value of the argument is incorporated into the path portion of the URI. Arguments specifying a *Location* of @query@ are incorporated into the query portion of the URI or request body. +The methods are relative to the base URI, e.g., @/arvados/v1/resource_type@. For arguments specifying a *Location* of @path@, the value of the argument is incorporated into the path portion of the URI. For example, a @uuid@ of @aaaaa-bbbbb-ccccccccccccccc@ in a path position yields a URI of @/arvados/v1/resource_type/aaaaa-bbbbb-ccccccccccccccc@. + +Arguments specifying a *Location* of @query@ are incorporated into the query portion of the URI or request body. For example, @/arvados/v1/resource_type?resource_type={}@. h2. create -The @create@ method creates a new object of the specified type. Note that only the listed attributes (and "standard metadata":resources.html) are set, unset attributes will get default values, and the attributes of a given resource type are fixed (you cannot introduce new toplevel attributes). It corresponds to the HTTP request @POST /arvados/v1/resource_type@. A successful create call returns a copy of the new object. +The @create@ method creates a new object of the specified type. Note that: + +* Only the listed attributes (and "standard metadata":resources.html) are set +* Unset attributes will get default values +* The attributes of a given resource type are fixed (you cannot introduce new toplevel attributes) + +This method corresponds to the HTTP request @POST /arvados/v1/resource_type@. A successful create call returns a copy of the new object. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location | -|{resource_type}|object|Name is the singular form of the resource type, e.g. for the "collections" resource, this argument is "collection"|query|| +|{resource_type}|object|Name is the singular form of the resource type, e.g., for the "collections" resource, this argument is "collection"|query|| h2. delete -The @delete@ method deletes a object of the specified type. It corresponds to the HTTP request @DELETE /arvados/v1/resource_type/uuid@. A successful delete call returns a copy of the deleted object. +The @delete@ method deletes an object of the specified type. It corresponds to the HTTP request @DELETE /arvados/v1/resource_type/uuid@. A successful delete call returns a copy of the deleted object. Arguments: @@ -42,15 +55,15 @@ table(table table-bordered table-condensed). h2(#index). list -The @list@ method requests an list of resources of that type. It corresponds to the HTTP request @GET /arvados/v1/resource_type@. All resources support listing with unless otherwise noted. +The @list@ method requests an list of resources of that type. It corresponds to the HTTP request @GET /arvados/v1/resource_type@. All resources support "list" method unless otherwise noted. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location | -|limit |integer|Maximum number of resources to return. May also be subject to server limit.|query| -|offset |integer|Skip the first 'offset' resources that match the given filter conditions.|query| -|filters |array |Conditions for selecting resources to return (see below).|query| +|limit |integer|Maximum number of resources to return. If not provided, server will provide a default limit. Server may also impose a maximum number of records that can be returned in a single request.|query| +|offset |integer|Skip the first 'offset' number of resources that would be returned under the given filter conditions.|query| +|filters |array |"Conditions for selecting resources to return.":#filters|query| |order |array |Attributes to use as sort keys to determine the order resources are returned, each optionally followed by @asc@ or @desc@ to indicate ascending or descending order. Example: @["head_uuid asc","modified_at desc"]@ Default: @["created_at desc"]@|query| @@ -59,8 +72,10 @@ Example: @["head_uuid","tail_uuid"]@ Default: all available attributes. As a special case, collections do not return "manifest_text" unless explicitly selected.|query| |distinct|boolean|@true@: (default) do not return duplicate objects @false@: permitted to return duplicates|query| +|count|string|@"exact"@ (default): Include an @items_available@ response field giving the number of distinct matching items that can be retrieved (irrespective of @limit@ and @offset@ arguments). +@"none"@: Omit the @items_available@ response field. This option will produce a faster response.|query| -h3. filters +h3(#filters). Available list method filters The value of the @filters@ parameter is an array of conditions. The @list@ method returns only the resources that satisfy all of the given conditions. In other words, the conjunction @AND@ is implicit. @@ -75,14 +90,29 @@ table(table table-bordered table-condensed). The following operators are available. table(table table-bordered table-condensed). -|_. Operator|_. Operand type|_. Example| -|@<@, @<=@, @>=@, @>@, @like@, @ilike@|string|@["script_version","like","d00220fb%"]@| -|@=@, @!=@|string or null|@["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"]@ -@["tail_uuid","!=",null]@| -|@in@, @not in@|array of strings|@["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]@| -|@is_a@|string|@["head_uuid","is_a","arvados#pipelineInstance"]@| - -h3. result +|_. Operator|_. Operand type|_. Description|_. Example| +|@=@, @!=@|string, number, timestamp, or null|Equality comparison|@["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"]@ @["tail_uuid","!=",null]@| +|@<@, @<=@, @>=@, @>@|string, number, or timestamp|Ordering comparison|@["script_version",">","123"]@| +|@like@, @ilike@|string|SQL pattern match. Single character match is @_@ and wildcard is @%@. The @ilike@ operator is case-insensitive|@["script_version","like","d00220fb%"]@| +|@in@, @not in@|array of strings|Set membership|@["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]@| +|@is_a@|string|Arvados object type|@["head_uuid","is_a","arvados#collection"]@| +|@exists@|string|Test if a subproperty is present.|@["properties","exists","my_subproperty"]@| + +h4. Filtering on subproperties + +Some record type have an additional @properties@ attribute that allows recording and filtering on additional key-value pairs. To filter on a subproperty, the value in the @attribute@ position has the form @properties.user_property@. You may also use JSON-LD / RDF style URIs for property keys by enclosing them in @<...>@ for example @properties.@. Alternately you may also provide a JSON-LD "@context" field, however at this time JSON-LD contexts are not interpreted by Arvados. + +table(table table-bordered table-condensed). +|_. Operator|_. Operand type|_. Description|_. Example| +|@=@, @!=@|string, number or boolean|Equality comparison|@["properties.my_subproperty", "=", "fizzy whizy sparkle pop"]@| +|@<@, @<=@, @>=@, @>@|string or number|Ordering comparison|@["properties.my_subproperty", "<", 3]@| +|@like@, @ilike@|string|SQL pattern match, single character match is @_@ and wildcard is @%@, ilike is case-insensitive|@["properties.my_subproperty", "like", "d00220fb%"]@| +|@in@, @not in@|array of strings|Set membership|@["properties.my_subproperty", "in", ["fizz", "buzz"]]@| +|@exists@|boolean|Test if a subproperty is present or not (determined by operand).|@["properties.my_subproperty", "exists", true]@| + +Note that exclusion filters @!=@ and @not in@ will return records for which the property is not defined at all. To restrict filtering to records on which the subproperty is defined, combine with an @exists@ filter. + +h3. Results of list method A successful call to list will return the following object.