odata_entitylist_data_get: Get the Data Document from the OData Dataset Service.
In dbca-wa/ruODK: An R Client for the ODK Central API
View source: R/odata_entitylist_data_get.R
odata_entitylist_data_get R Documentation
Get the Data Document from the OData Dataset Service.
Description
![[Experimental]](../help/figures/lifecycle-experimental.svg)
Usage
odata_entitylist_data_get(
pid = get_default_pid(),
did = "",
query = NULL,
url = get_default_url(),
un = get_default_un(),
pw = get_default_pw(),
retries = get_retries(),
odkc_version = get_default_odkc_version(),
orders = get_default_orders(),
tz = get_default_tz()
)
Arguments
pid
The numeric ID of the project, e.g.: 2.
Default: get_default_pid.
Set default pid through ru_setup(pid="...").
See vignette("Setup", package = "ruODK").
did
(chr) The name of the Entity List, internally called Dataset.
The function will error if this parameter is not given.
Default: "".
query
An optional named list of query parameters, e.g.
list(
"$filter" = "__system/createdAt le 2024-11-05",
"$orderby" = "__system/creatorId ASC, __system/conflict DESC",
"$top" = "100",
"$skip" = "3",
"$count" = "true"
)
No validation is conducted by ruODK on the query list prior to
passing it to ODK Central.
If omitted, no filter query is sent.
Note that the behaviour of this parameter differs from the implementation
of odata_submission_get() in that query here accepts a list of all
possible OData query parameters and odata_submission_get() offers
individual function parameters matching supported OData query parameters.
Default: NULL
url
The ODK Central base URL without trailing slash.
Default: get_default_url.
Set default url through ru_setup(url="...").
See vignette("Setup", package = "ruODK").
un
The ODK Central username (an email address).
Default: get_default_un.
Set default un through ru_setup(un="...").
See vignette("Setup", package = "ruODK").
pw
The ODK Central password.
Default: get_default_pw.
Set default pw through ru_setup(pw="...").
See vignette("Setup", package = "ruODK").
retries
The number of attempts to retrieve a web resource.
This parameter is given to RETRY(times = retries).
Default: 3.
odkc_version
The ODK Central version as a semantic version string
(year.minor.patch), e.g. "2023.5.1". The version is shown on ODK Central's
version page /version.txt. Discard the "v".
ruODK uses this parameter to adjust for breaking changes in ODK Central.
Default: get_default_odkc_version or "2023.5.1" if unset.
Set default get_default_odkc_version through
ru_setup(odkc_version="2023.5.1").
See vignette("Setup", package = "ruODK").
orders
(vector of character) Orders of datetime elements for
lubridate.
Default:
c("YmdHMS", "YmdHMSz", "Ymd HMS", "Ymd HMSz", "Ymd", "ymd").
tz
A timezone to convert dates and times to.
Read vignette("setup", package = "ruODK") to learn how ruODK's
timezone can be set globally or per function.
Details
All the Entities in a Dataset.
The $top and $skip querystring parameters, specified by OData, apply limit
and offset operations to the data, respectively.
The $count parameter, also an OData standard, will annotate the response
data with the total row count, regardless of the scoping requested by $top
and $skip.
If $top parameter is provided in the request then the response will include
@odata.nextLink that you can use as is to fetch the next set of data.
As of ODK Central v2023.4, @odata.nextLink contains a $skiptoken
(an opaque cursor) to better paginate around deleted Entities.
The $filter querystring parameter can be used to filter certain data fields
in the system-level schema, but not the Dataset properties.
The operators lt, le, eq, ne, ge, gt, not, and, and or
and the built-in functions now, year, month, day, hour,
minute, second are supported.
The fields you can query against are as follows:
Entity Metadata: OData Field Name
Entity Creator Actor ID: __system/creatorId
Entity Timestamp: __system/createdAt
Entity Update Timestamp: __system/updatedAt
Entity Conflict: __system/conflict
Note that createdAt and updatedAt are time components.
This means that any comparisons you make need to account for the full time
of the entity. It might seem like $filter=__system/createdAt le 2020-01-31
would return all results on or before 31 Jan 2020, but in fact only entities
made before midnight of that day would be accepted.
To include all of the month of January, you need to filter by either
$filter=__system/createdAt le 2020-01-31T23:59:59.999Z or
$filter=__system/createdAt lt 2020-02-01.
Remember also that you can query by a specific timezone.
Please see the OData documentation on $filter
operations
and functions
for more information.
The $select query parameter will return just the fields you specify and is
supported on __id, __system, __system/creatorId, __system/createdAt
and __system/updatedAt, as well as on user defined properties.
The $orderby query parameter will return Entities sorted by different
fields, which come from the same list used by $filter, as noted above.
The order can be specified as ASC (ascending) or DESC (descending),
which are case-insensitive. Multiple sort expressions can be used together,
separated by commas,
e.g. $orderby=__system/creatorId ASC, __system/conflict DESC.
As the vast majority of clients only support the JSON OData format,
that is the only format ODK Central offers.
Value
An S3 class odata_entitylist_data_get with two list items:
-
context The URL for the OData metadata document
-
value A tibble of EntitySets available in this EntityList, with names
cleaned by janitor::clean_names() and unnested list columns
(__system).
See Also
https://docs.getodk.org/central-api-odata-endpoints/#id3
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948
Other entity-management:
entity_audits(),
entity_changes(),
entity_create(),
entity_delete(),
entity_detail(),
entity_list(),
entity_update(),
entity_versions(),
entitylist_detail(),
entitylist_download(),
entitylist_list(),
entitylist_update(),
odata_entitylist_metadata_get(),
odata_entitylist_service_get()
Examples
## Not run:
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")
ds <- entitylist_list(pid = get_default_pid())
ds1 <- odata_entitylist_data_get(pid = get_default_pid(), did = ds$name[1])
ds1
ds1$context
ds1$value
qry <- list(
"$filter" = "__system/createdAt le 2024-11-05",
"$orderby" = "__system/creatorId ASC, __system/conflict DESC",
"$top" = "100",
"$skip" = "3",
"$count" = "true"
)
ds2 <- odata_entitylist_data_get(
pid = get_default_pid(),
did = ds$name[1],
query = qry
)
ds2
## End(Not run)
dbca-wa/ruODK documentation built on Nov. 8, 2024, 4:09 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/odata_entitylist_data_get.R
| odata_entitylist_data_get | R Documentation |
Get the Data Document from the OData Dataset Service.
Description
Usage
odata_entitylist_data_get(
pid = get_default_pid(),
did = "",
query = NULL,
url = get_default_url(),
un = get_default_un(),
pw = get_default_pw(),
retries = get_retries(),
odkc_version = get_default_odkc_version(),
orders = get_default_orders(),
tz = get_default_tz()
)
Arguments
pid |
The numeric ID of the project, e.g.: 2. Default: Set default See |
did |
(chr) The name of the Entity List, internally called Dataset. The function will error if this parameter is not given. Default: "". |
query |
An optional named list of query parameters, e.g. list( "$filter" = "__system/createdAt le 2024-11-05", "$orderby" = "__system/creatorId ASC, __system/conflict DESC", "$top" = "100", "$skip" = "3", "$count" = "true" ) No validation is conducted by |
url |
The ODK Central base URL without trailing slash. Default: Set default See |
un |
The ODK Central username (an email address).
Default: |
pw |
The ODK Central password.
Default: |
retries |
The number of attempts to retrieve a web resource. This parameter is given to Default: 3. |
odkc_version |
The ODK Central version as a semantic version string
(year.minor.patch), e.g. "2023.5.1". The version is shown on ODK Central's
version page Default: Set default See |
orders |
(vector of character) Orders of datetime elements for lubridate. Default:
|
tz |
A timezone to convert dates and times to. Read |
Details
All the Entities in a Dataset.
The $top and $skip querystring parameters, specified by OData, apply limit
and offset operations to the data, respectively.
The $count parameter, also an OData standard, will annotate the response
data with the total row count, regardless of the scoping requested by $top
and $skip.
If $top parameter is provided in the request then the response will include
@odata.nextLink that you can use as is to fetch the next set of data.
As of ODK Central v2023.4, @odata.nextLink contains a $skiptoken
(an opaque cursor) to better paginate around deleted Entities.
The $filter querystring parameter can be used to filter certain data fields
in the system-level schema, but not the Dataset properties.
The operators lt, le, eq, ne, ge, gt, not, and, and or
and the built-in functions now, year, month, day, hour,
minute, second are supported.
The fields you can query against are as follows:
Entity Metadata: OData Field Name
Entity Creator Actor ID: __system/creatorId
Entity Timestamp: __system/createdAt
Entity Update Timestamp: __system/updatedAt
Entity Conflict: __system/conflict
Note that createdAt and updatedAt are time components.
This means that any comparisons you make need to account for the full time
of the entity. It might seem like $filter=__system/createdAt le 2020-01-31
would return all results on or before 31 Jan 2020, but in fact only entities
made before midnight of that day would be accepted.
To include all of the month of January, you need to filter by either
$filter=__system/createdAt le 2020-01-31T23:59:59.999Z or
$filter=__system/createdAt lt 2020-02-01.
Remember also that you can query by a specific timezone.
Please see the OData documentation on $filter
operations
and functions
for more information.
The $select query parameter will return just the fields you specify and is
supported on __id, __system, __system/creatorId, __system/createdAt
and __system/updatedAt, as well as on user defined properties.
The $orderby query parameter will return Entities sorted by different
fields, which come from the same list used by $filter, as noted above.
The order can be specified as ASC (ascending) or DESC (descending),
which are case-insensitive. Multiple sort expressions can be used together,
separated by commas,
e.g. $orderby=__system/creatorId ASC, __system/conflict DESC.
As the vast majority of clients only support the JSON OData format, that is the only format ODK Central offers.
Value
An S3 class odata_entitylist_data_get with two list items:
-
contextThe URL for the OData metadata document -
valueA tibble of EntitySets available in this EntityList, with names cleaned byjanitor::clean_names()and unnested list columns (__system).
See Also
https://docs.getodk.org/central-api-odata-endpoints/#id3
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31358948
Other entity-management:
entity_audits(),
entity_changes(),
entity_create(),
entity_delete(),
entity_detail(),
entity_list(),
entity_update(),
entity_versions(),
entitylist_detail(),
entitylist_download(),
entitylist_list(),
entitylist_update(),
odata_entitylist_metadata_get(),
odata_entitylist_service_get()
Examples
## Not run:
# See vignette("setup") for setup and authentication options
# ruODK::ru_setup(svc = "....svc", un = "me@email.com", pw = "...")
ds <- entitylist_list(pid = get_default_pid())
ds1 <- odata_entitylist_data_get(pid = get_default_pid(), did = ds$name[1])
ds1
ds1$context
ds1$value
qry <- list(
"$filter" = "__system/createdAt le 2024-11-05",
"$orderby" = "__system/creatorId ASC, __system/conflict DESC",
"$top" = "100",
"$skip" = "3",
"$count" = "true"
)
ds2 <- odata_entitylist_data_get(
pid = get_default_pid(),
did = ds$name[1],
query = qry
)
ds2
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.