2 Application Programming Interface (API)
Programmatic access (API)
The EBRAINS Knowledge Graph provides convenient tools and APIs for the implementation of queries into your scripts.
To be able to access the Knowledge Graph (KG) programmatically, you only require an EBRAINS account. Register for an account here: https://ebrains.eu/register/ and log in.
Writing Knowledge Graph queries
A query for the Knowledge Graph is defined declaratively in JSON-LD and is always executed against a specific data structure (e.g. a "Dataset version"), allowing the graph to be traversed.
In the snippet below, we can see that we first define the semantical context for the query with "@context", which belongs to the namespace "https://schema.hbp.eu/graphQuery/".
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
"@context": {
"@vocab": "https://core.kg.ebrains.eu/vocab/query/",
"query": "https://schema.hbp.eu/myQuery/",
"propertyName": {
"@id": "propertyName",
"@type": "@id"
},
"path": {
"@id": "path",
"@type": "@id"
}
},
"meta": {
"type": "https://openminds.ebrains.eu/core/DatasetVersion",
"responseVocab": "https://schema.hbp.eu/myQuery/"
},
"structure": {
"propertyName": "query:DatasetVersionTitle",
"path": "https://openminds.ebrains.eu/vocab/shortName"
}
}
Query Builder
The query builder allows you to make, save, and reuse complex queries without any knowledge of graph query languages.
Go to the Query Builder: https://query.kg.ebrains.eu
Select a category
A query for the Knowledge Graph is always executed against a specific data structure (e.g. a "Dataset version"). First select the data structure for your query.
Select an experimental approach
Similar to the faceted filters in the Knowledge Graph Search UI, we can refine our query by defining the experimental approach of our interest, for example electrophysiology.
To ensure that all dataset versions with electrophysiology are queried, and none of the dataset versions without electrophysiology, we make this property required and we apply a filter to the label we are searching for (i.e. electrophysiology).
Select species
We can also refine our query to only include dataset versions that use mice (mus musculus) in a similar way as the faceted filters in the Search UI.
Access detailed metadata
The Knowledge Graph Search UI has visualised the basic metadata. In many cases, more metadata is stored in the KG than is readily accessible via the Search UI. We can use this to our advantage when refining our query.
For example, we can filter datasets with data from male subjects by making this a required feature in the query (set the label of "biologicalSex" to "male).
The above query in the Query Builder is written below:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
"@context": {
"@vocab": "https://core.kg.ebrains.eu/vocab/query/",
"query": "https://schema.hbp.eu/myQuery/",
"propertyName": {
"@id": "propertyName",
"@type": "@id"
},
"path": {
"@id": "path",
"@type": "@id"
}
},
"meta": {
"type": "https://openminds.ebrains.eu/core/DatasetVersion",
"responseVocab": "https://schema.hbp.eu/myQuery/"
},
"structure": [
{
"propertyName": "query:experimentalApproach",
"path": "https://openminds.ebrains.eu/vocab/experimentalApproach",
"required": true,
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name",
"required": true,
"filter": {
"op": "CONTAINS",
"value": "electrophysiology"
}
}
},
{
"propertyName": "query:studiedSpecimen",
"path": "https://openminds.ebrains.eu/vocab/studiedSpecimen",
"structure": [
{
"propertyName": "query:species",
"path": "https://openminds.ebrains.eu/vocab/species",
"required": true,
"structure": [
{
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name"
},
{
"propertyName": "query:species",
"path": "https://openminds.ebrains.eu/vocab/species",
"required": true,
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name",
"required": true,
"filter": {
"op": "CONTAINS",
"value": "mus musculus"
}
}
}
]
},
{
"propertyName": "query:lookupLabel",
"path": "https://openminds.ebrains.eu/vocab/lookupLabel"
},
{
"propertyName": "query:biologicalSex",
"path": "https://openminds.ebrains.eu/vocab/biologicalSex",
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name",
"required": true,
"filter": {
"op": "CONTAINS",
"value": "male"
}
}
},
{
"propertyName": "query:studiedState",
"path": "https://openminds.ebrains.eu/vocab/studiedState",
"structure": [
{
"propertyName": "query:lookupLabel",
"path": "https://openminds.ebrains.eu/vocab/lookupLabel"
},
{
"propertyName": "query:age",
"path": "https://openminds.ebrains.eu/vocab/age",
"structure": [
{
"propertyName": "query:value",
"path": "https://openminds.ebrains.eu/vocab/value"
},
{
"propertyName": "query:unit",
"path": "https://openminds.ebrains.eu/vocab/unit",
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name"
}
}
]
},
{
"propertyName": "query:ageCategory",
"path": "https://openminds.ebrains.eu/vocab/ageCategory",
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name"
}
},
{
"propertyName": "query:attribute",
"path": "https://openminds.ebrains.eu/vocab/attribute",
"structure": {
"propertyName": "query:name",
"path": "https://openminds.ebrains.eu/vocab/name"
}
}
]
}
]
}
]
}