Skip to main content

Select Clauses

The select clause determines what data is returned from a query. It defines the shape of your results.

select​

required?type
yesarray or object

A select can be either a select object or a select array.

Select Object​

With a select object, each key is a logic variable name and the value is an array of select expressions.

The select clause determines what objects are returned in query results. Each logic variable corresponds to a set of subjects, and a JSON object gets constructed for each subject. The array of select expressions describes how to build these JSON objects by specifying what predicates to include.

Select Object Examples​

Simple select example

{
"select": {
"?s": [
"name",
{ "bestFriend": ["*"] }
]
},
"where": {
"@id": "?s",
"bestFriend": "?friend"
}
}

Select Array​

With a select array, each element is a logic variable name or a select object. When your select clause is a select array, each element of the query results is an array.

Select Array Examples​

Logic variable

{
"select": ["?s", "?name", "?friend"],
"where": {
"@id": "?s",
"bestFriend": "?friend",
"name": "?name"
}
}

Logic variable and a select object

{
"select": [
{ "?s": ["*"] },
{ "?friend": ["*"] }
],
"where": {
"@id": "?s",
"bestFriend": "?friend",
"name": "?name"
}
}

Logic Variable Name​

Logic variables are placeholders for sets of subjects. They are identified by logic variable names.

Logic variable names are strings that begin with a question mark, ?, followed by alphanumeric characters, hyphens, and underscores.

See Querying Basics for information about logic variables.

Examples​


"?firstname"
"?first-name"
"?first_name"
"?address-1"

Select Expression​

Select clause objects map logic variables to select expressions. In the select clause below, "?s" identifies a logic variable and ["name", { "bestFriend": ["*"] }] is a select expression.


{
"select": {
"?s": [
"name",
{ "bestFriend": ["*"] }
]
},
"where": { ... }
}

Select expressions describe the shape of data to be returned for subjects. It specifies what predicates to include in the result object, and how to traverse predicates to return nested values.

A select expression can be one of:

  • A predicate, like "schema:name". When included, the corresponding value is returned in the result object.
  • The wildcard symbol, "*". When included, all of a subject's predicates are included in its result object.
  • A node object template. This describes how to traverse nested predicate values.

Examples​


// wildcard
"*"
// predicate
"schema:name"
// node object template; see below
{
"schema:address": ["*"]
}

Node Object Template​

Node object templates are objects where the keys are predicates, and the values are arrays of select expressions. Node object templates express for the given predicate, construct an object that contains the predicates described by the array of select expressions.


{
predicate: [select-expression, select-expression, ...],
predicate: [select-expression, select-expression, ...],
...
}

Examples​

Return an object that has all predicates for the node that "bestFriend" refers to

{
"select": {
"?s": [
{ "bestFriend": ["*"] }
]
},
"where": { ... }
}

Multi-level nested object

{
"select": {
"?s": [
{
"bestFriend": [
{
"address": [
"*"
]
}
]
}
]
},
"where": { ... }
}

construct​

required?type
no*array

The construct clause builds custom JSON-LD output from query results, similar to SPARQL CONSTRUCT queries. Use construct instead of select when you want to transform query results into a specific shape.

NOTE: Either select or construct is required, but not both.

Basic Construct​


{
"from": "my-ledger",
"construct": [
{
"@id": "?s",
"@type": "ex:SearchResult",
"ex:displayName": "?name"
}
],
"where": { "@id": "?s", "schema:name": "?name" }
}

Example Response​


{
"@graph": [
{
"@id": "ex:alice",
"@type": ["ex:SearchResult"],
"ex:displayName": ["Alice"]
},
{
"@id": "ex:bob",
"@type": ["ex:SearchResult"],
"ex:displayName": ["Bob"]
}
]
}

The construct clause returns a JSON-LD document with an @graph array containing the constructed nodes.

Next Steps​