Item-level data access (endpoint name Item)¶
The Item service returns detailed data for a single record retrieved using either an internal CollectiveAccess ID value or the idno value of the record.
To fetch a record pass the table, identifier and list of bundles to return in a get query. You can list any number of bundles, and include bundles in related tables. You may also specify display templates.
Tip
Display templates can be used to format arbitrarily complex data extracted from returned records, as well as directly and indirectly related records. They are evaluated relative to the specified item.
query {
get(
table: "ca_objects",
identifier: "test.1",
bundles: ["ca_objects.idno", "ca_objects.type_id", "ca_objects.preferred_labels.name", "ca_objects.nonpreferred_labels", "ca_objects.description", "<strong>[^ca_objects.type_id]</strong>: <unit relativeTo='ca_entities' delimiter='; '>^ca_entities.preferred_labels.surname, ^ca_entities.preferred_labels.forename</unit>"]
) {
id,
table,
idno,
bundles {
name,
code,
dataType,
values {
locale,
value,
subvalues {
code,
value,
dataType
}
}
}
}
}
The query will return:
{
"ok": true,
"data": {
"get": {
"id": 10,
"table": "ca_objects",
"idno": null,
"bundles": [
{
"name": "Object identifier",
"code": "ca_objects.idno",
"dataType": "Text",
"values": [
{
"locale": null,
"value": "test.1",
"subvalues": null
}
]
},
{
"name": "Type",
"code": "ca_objects.type_id",
"dataType": "Text",
"values": [
{
"locale": null,
"value": "artifact_item",
"subvalues": null
}
]
},
{
"name": "Name",
"code": "ca_objects.preferred_labels.name",
"dataType": null,
"values": [
{
"locale": "en_US",
"value": "My first record",
"subvalues": [
{
"code": "name",
"value": "My first record",
"dataType": "Text"
}
]
}
]
},
{
"name": "Description",
"code": "ca_objects.description",
"dataType": "Text",
"values": [
{
"locale": "en_US",
"value": "Drop the Dips was a roller coaster in Coney Island, NY",
"subvalues": [
{
"code": "description",
"value": "Drop the Dips was a roller coaster in Coney Island, NY",
"dataType": "Text"
}
]
}
]
},
,
{
"name": "<strong>[^ca_objects.type_id]</strong>: <unit relativeTo='ca_entities' delimiter='; '>^ca_entities.preferred_labels.surname, ^ca_entities.preferred_labels.forename</unit>",
"code": "<strong>[^ca_objects.type_id]</strong>: <unit relativeTo='ca_entities' delimiter='; '>^ca_entities.preferred_labels.surname, ^ca_entities.preferred_labels.forename</unit>",
"dataType": "Text",
"values": [
{
"locale": "en_US",
"value": "<strong>Postcard</strong>: Tilyou, George; Dundee, Elmer; Thompson, Fred",
"subvalues": [
{
"code": "description",
"value": "<strong>Postcard</strong>: Tilyou, George; Dundee, Elmer; Thompson, Fred",
"dataType": "Text"
}
]
}
]
}
]
}
}
}
Including bundles referring to related tables will include relationship data in the item response. For example, adding ca_entities to the query would return:
Note
The identifier parameter value matches records using either CollectiveAccess ID (an application-generated unique integer value) or idno (a user-set alphanumeric value that is typically, but not necessarily, unique). Matching is performed first on CollectiveAccess ID and then on idno values. While idno values typically include letters and punctation that clearly distinguish them from purely integer CollectiveAccess IDs, this is not always the case. Use of integers for idno values will introduce ambiguities as a value may match both CollectiveAccess ID and idno values. To constrain which values are used for matching set the id or idno input parameters instead of identifier. id will match only on CollectiveAccess IDs. idno will match only on user-set idno values.
Fetching relationships for an item¶
Use the getRelationships query to fetch a list of relationships between an item and items in another table. You can filter the returned list to only include related items or relationships with specific types via the restrictToTypes and restrictToRelationshipTypes parameters.
query {
getRelationships(
table: "ca_objects",
identifier: "test.1",
target:"ca_entities",
bundles: [
"ca_entities.preferred_labels.displayname", "ca_entities.txt_biography"], restrictToRelationshipTypes: ["donor"]
) {
id,
table,
idno,
relationships {
id,
table,
relationship_typename,
relationship_typecode,
bundles {
name,
code,
dataType,
values {
id,
value_id,
locale,
value,
subvalues {
id,
code,
value,
dataType
}
}
}
}
}
}
returns:
{
"ok": true,
"data": {
"getRelationships": {
"id": 10,
"table": "ca_objects",
"idno": "test.1",
"relationships": [
{
"id": 11,
"table": "ca_objects_x_entities",
"relationship_typename": "Donor",
"relationship_typecode": "donor",
"bundles": [
{
"name": "Display name (from entities)",
"code": "ca_entities.preferred_labels.displayname",
"dataType": "Container",
"values": [
{
"id": 52,
"value_id": null,
"locale": "en_US",
"value": "Fay Abrams",
"subvalues": [
{
"id": null,
"code": "displayname",
"value": "Fay Abrams",
"dataType": "Container"
}
]
}
]
},
{
"name": "Biography (from entities)",
"code": "ca_entities.txt_biography",
"dataType": "Text",
"values": [
{
"id": 472,
"value_id": 856,
"locale": "en_US",
"value": "Hello there!",
"subvalues": [
{
"id": 856,
"code": "txt_biography",
"value": "Hello there!",
"dataType": "Text"
}
]
}
]
}
]
}
]
}
}
}
Tip
Value_id values are returned in the subvalues list for metadata elements. Valid_id’s are unique numeric identifiers assigned automatically by CollectiveAccess for each individual metadata value attached to a record. These ids can be used to refer to a specific value for editing or deletion.
Fetching different relationships for an item in a single query¶
Some applications need to fetch a variety of relationships for an item at once. Issuing a separate query for each relationship type may impacts performance. It is possible to fetch any number of relationships for an item using the targets option. Each target may include any of the options used in a simple getRelationships query. This query will return up to five objects and/or donor entities of type individual related to object 2022.001:
query {
getRelationships(
table: "ca_objects",
idno: "2022.001",
targets:[
{
name: "related_objects",
start: 0,
limit: 5,
table: "ca_objects",
bundles: ["ca_objects.preferred_labels.name", "ca_objects.idno"]
},
{
name: "related_entities",
start: 0,
limit: 5,
table: "ca_entities",
restrictToTypes: ["individual"],
restrictToRelationshipTypes:["donor"],
bundles: ["ca_entities.preferred_labels.displayname", "ca_entities.idno"]
}
]
) {
id,
table,
idno,
targets {
name,
relationships {
relationship_typename,
relationship_typecode,
id,
table,
bundles {
name,
code,
dataType,
values {
id,
value_id,
locale,
value,
subvalues {
id,
code,
value,
dataType
}
}
}
}
}
}
}
The response:
{
"ok": true,
"data": {
"getRelationships": {
"id": 2379,
"table": "ca_objects",
"idno": "2022.001",
"targets": [
{
"name": "related_objects",
"relationships": [
{
"relationship_typename": "is related to (forward)",
"relationship_typecode": "related",
"id": 59,
"table": "ca_objects_x_objects",
"bundles": [
{
"name": "Name (from art objects)",
"code": "ca_objects.preferred_labels.name",
"dataType": null,
"values": [
{
"id": 6139,
"value_id": null,
"locale": "en_US",
"value": "Madonna and Child",
"subvalues": [
{
"id": null,
"code": "name",
"value": "Madonna and Child",
"dataType": null
}
]
}
]
},
{
"name": "Object identifier (from art objects)",
"code": "ca_objects.idno",
"dataType": null,
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "3349",
"subvalues": [
{
"id": null,
"code": "0",
"value": "3349",
"dataType": null
}
]
}
]
}
]
},
{
"relationship_typename": "is related to (reverse)",
"relationship_typecode": "related",
"id": 61,
"table": "ca_objects_x_objects",
"bundles": [
{
"name": "Name (from art objects)",
"code": "ca_objects.preferred_labels.name",
"dataType": "Container",
"values": [
{
"id": 4941,
"value_id": null,
"locale": "en_US",
"value": "The Adoration of the Magi",
"subvalues": [
{
"id": null,
"code": "name",
"value": "The Adoration of the Magi",
"dataType": "Container"
}
]
}
]
},
{
"name": "Object identifier (from art objects)",
"code": "ca_objects.idno",
"dataType": "Container",
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "2047",
"subvalues": [
{
"id": null,
"code": "0",
"value": "2047",
"dataType": null
}
]
}
]
}
]
},
{
"relationship_typename": "is related to (forward)",
"relationship_typecode": "related",
"id": 62,
"table": "ca_objects_x_objects",
"bundles": [
{
"name": "Name (from art objects)",
"code": "ca_objects.preferred_labels.name",
"dataType": "Container",
"values": [
{
"id": 5134,
"value_id": null,
"locale": "en_US",
"value": "The Presentation in the Temple",
"subvalues": [
{
"id": null,
"code": "name",
"value": "The Presentation in the Temple",
"dataType": "Container"
}
]
}
]
},
{
"name": "Object identifier (from art objects)",
"code": "ca_objects.idno",
"dataType": "Container",
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "2271",
"subvalues": [
{
"id": null,
"code": "0",
"value": "2271",
"dataType": null
}
]
}
]
}
]
}
]
},
{
"name": "related_entities",
"relationships": [
{
"relationship_typename": "Artist",
"relationship_typecode": "artist",
"id": 1901,
"table": "ca_objects_x_entities",
"bundles": [
{
"name": "Display name (from name authorities)",
"code": "ca_entities.preferred_labels.displayname",
"dataType": "Container",
"values": [
{
"id": 137,
"value_id": null,
"locale": "en_US",
"value": "Bolognese 15th Century",
"subvalues": [
{
"id": null,
"code": "displayname",
"value": "Bolognese 15th Century",
"dataType": null
}
]
}
]
},
{
"name": "Name Authority identifier (from name authorities)",
"code": "ca_entities.idno",
"dataType": "Container",
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "NAM0144",
"subvalues": [
{
"id": null,
"code": "0",
"value": "NAM0144",
"dataType": null
}
]
}
]
}
]
},
{
"relationship_typename": "Artist",
"relationship_typecode": "artist",
"id": 1902,
"table": "ca_objects_x_entities",
"bundles": [
{
"name": "Display name (from name authorities)",
"code": "ca_entities.preferred_labels.displayname",
"dataType": "Container",
"values": [
{
"id": 138,
"value_id": null,
"locale": "en_US",
"value": "Bolognese 16th Century",
"subvalues": [
{
"id": null,
"code": "displayname",
"value": "Bolognese 16th Century",
"dataType": "Container"
}
]
}
]
},
{
"name": "Name Authority identifier (from name authorities)",
"code": "ca_entities.idno",
"dataType": "Container",
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "NAM0145",
"subvalues": [
{
"id": null,
"code": "0",
"value": "NAM0145",
"dataType": null
}
]
}
]
}
]
},
{
"relationship_typename": "location",
"relationship_typecode": "location",
"id": 1903,
"table": "ca_objects_x_entities",
"bundles": [
{
"name": "Display name (from name authorities)",
"code": "ca_entities.preferred_labels.displayname",
"dataType": "Container",
"values": [
{
"id": 777,
"value_id": null,
"locale": "en_US",
"value": "National Gallery of Art, Washington, District of Columbia",
"subvalues": [
{
"id": null,
"code": "displayname",
"value": "National Gallery of Art, Washington, District of Columbia",
"dataType": "Container"
}
]
}
]
},
{
"name": "Name Authority identifier (from name authorities)",
"code": "ca_entities.idno",
"dataType": "Container",
"values": [
{
"id": 0,
"value_id": null,
"locale": "en_US",
"value": "NAM0858",
"subvalues": [
{
"id": null,
"code": "0",
"value": "NAM0858",
"dataType": null
}
]
}
]
}
]
}
]
}
]
}
}
}
Limiting results using access values¶
All primary records in CollectiveAccess include an access field to control visibility in public-facing contexts such as web sites and data feeds. Data in the getRelationships query can be limited by one or more access values using the checkAccess parameter, set to a list of integer access codes, as defined in the access_statuses list for the CollectiveAccess installation. By convention 0 indicates a private record, 1 a public record and 2 a record available in public interfaces to users with elevated privileges. However, these values may be vary across installations and should be verified before use.