Skip to content

Commit 60024f9

Browse files
RKrahlRKrahl
committed
Update the tutotial section "Searching for objects in the ICAT server"
to use the new format of the conditions argument when creating queries.
1 parent cfc9099 commit 60024f9

2 files changed

Lines changed: 81 additions & 81 deletions

File tree

‎doc/src/tutorial-search.rst‎

Lines changed: 42 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -119,11 +119,11 @@ that lists all investigations::
119119

120120
In order to search for a particular investigation, we may add an
121121
appropriate condition. The `conditions` argument to
122-
:class:`~icat.query.Query` should be a mapping of attribute names to
123-
conditions on that attribute::
122+
:class:`~icat.query.Query` should be a list of tuples, each of them
123+
being a pair of an attribute name and a conditions on that attribute::
124124

125125
>>> query = Query(client, "Investigation",
126-
... conditions={"name": "= '10100601-ST'"})
126+
... conditions=[("name", "= '10100601-ST'")])
127127
>>> print(query)
128128
SELECT o FROM Investigation o WHERE o.name = '10100601-ST'
129129
>>> client.search(query)
@@ -146,7 +146,7 @@ conditions on that attribute::
146146
We may also include related objects in the search results::
147147

148148
>>> query = Query(client, "Investigation",
149-
... conditions={"name": "= '10100601-ST'"},
149+
... conditions=[("name", "= '10100601-ST'")],
150150
... includes=["datasets"])
151151
>>> print(query)
152152
SELECT o FROM Investigation o WHERE o.name = '10100601-ST' INCLUDE o.datasets
@@ -212,7 +212,7 @@ which attribute a condition should be applied to. Consider the
212212
following query::
213213

214214
>>> query = Query(client, "Investigation",
215-
... conditions={"LENGTH(title)": "= 18"})
215+
... conditions=[("LENGTH(title)", "= 18")])
216216
>>> print(query)
217217
SELECT o FROM Investigation o WHERE LENGTH(o.title) = 18
218218
>>> client.search(query)
@@ -251,12 +251,12 @@ objects. This allows rather complex queries. Let us search for the
251251
datasets in this investigation that have been measured in a magnetic
252252
field larger then 5 Tesla and include its parameters in the result::
253253

254-
>>> conditions = {
255-
... "investigation.name": "= '10100601-ST'",
256-
... "parameters.type.name": "= 'Magnetic field'",
257-
... "parameters.type.units": "= 'T'",
258-
... "parameters.numericValue": "> 5.0",
259-
... }
254+
>>> conditions = [
255+
... ("investigation.name", "= '10100601-ST'"),
256+
... ("parameters.type.name", "= 'Magnetic field'"),
257+
... ("parameters.type.units", "= 'T'"),
258+
... ("parameters.numericValue", "> 5.0"),
259+
... ]
260260
>>> query = Query(client, "Dataset",
261261
... conditions=conditions, includes=["parameters.type"])
262262
>>> print(query)
@@ -337,9 +337,9 @@ of your Python program. Consider::
337337

338338
>>> def get_investigation(client, name, visitId=None):
339339
... query = Query(client, "Investigation")
340-
... query.addConditions({"name": "= '%s'" % name})
340+
... query.addConditions([("name", "= '%s'" % name)])
341341
... if visitId is not None:
342-
... query.addConditions({"visitId": "= '%s'" % visitId})
342+
... query.addConditions([("visitId", "= '%s'" % visitId)])
343343
... print(query)
344344
... return client.assertedSearch(query)[0]
345345
...
@@ -382,13 +382,12 @@ either by `name` alone or by `name` and `visitId`, depending on the
382382
arguments.
383383

384384
It is also possible to put more then one conditions on a single
385-
attribute: setting the corresponding value in the `conditions`
386-
argument to a list of strings will result in combining the conditions
387-
on that attribute. Search for all datafiles created in 2012::
385+
attribute. Search for all datafiles created in 2012::
388386

389-
>>> conditions = {
390-
... "datafileCreateTime": [">= '2012-01-01'", "< '2013-01-01'"]
391-
... }
387+
>>> conditions = [
388+
... ("datafileCreateTime", ">= '2012-01-01'"),
389+
... ("datafileCreateTime", "< '2013-01-01'"),
390+
... ]
392391
>>> query = Query(client, "Datafile", conditions=conditions)
393392
>>> print(query)
394393
SELECT o FROM Datafile o WHERE o.datafileCreateTime >= '2012-01-01' AND o.datafileCreateTime < '2013-01-01'
@@ -440,8 +439,8 @@ Of course, that last example also works when adding the conditions
440439
incrementally::
441440

442441
>>> query = Query(client, "Datafile")
443-
>>> query.addConditions({"datafileCreateTime": ">= '2012-01-01'"})
444-
>>> query.addConditions({"datafileCreateTime": "< '2013-01-01'"})
442+
>>> query.addConditions([("datafileCreateTime", ">= '2012-01-01'")])
443+
>>> query.addConditions([("datafileCreateTime", "< '2013-01-01'")])
445444
>>> print(query)
446445
SELECT o FROM Datafile o WHERE o.datafileCreateTime >= '2012-01-01' AND o.datafileCreateTime < '2013-01-01'
447446

@@ -487,11 +486,11 @@ transferring them to the client, and counting them at client side.
487486
Let's check for a given investigation, the minimum, maximum, and
488487
average magnetic field applied in the measurements::
489488

490-
>>> conditions = {
491-
... "dataset.investigation.name": "= '10100601-ST'",
492-
... "type.name": "= 'Magnetic field'",
493-
... "type.units": "= 'T'",
494-
... }
489+
>>> conditions = [
490+
... ("dataset.investigation.name", "= '10100601-ST'"),
491+
... ("type.name", "= 'Magnetic field'"),
492+
... ("type.units", "= 'T'"),
493+
... ]
495494
>>> query = Query(client, "DatasetParameter",
496495
... conditions=conditions, attributes="numericValue")
497496
>>> print(query)
@@ -517,10 +516,10 @@ average magnetic field applied in the measurements::
517516
For another example, let's search for all investigations, having any
518517
dataset with a magnetic field parameter set::
519518

520-
>>> conditions = {
521-
... "datasets.parameters.type.name": "= 'Magnetic field'",
522-
... "datasets.parameters.type.units": "= 'T'",
523-
... }
519+
>>> conditions = [
520+
... ("datasets.parameters.type.name", "= 'Magnetic field'"),
521+
... ("datasets.parameters.type.units", "= 'T'"),
522+
... ]
524523
>>> query = Query(client, "Investigation", conditions=conditions)
525524
>>> print(query)
526525
SELECT o FROM Investigation o JOIN o.datasets AS s1 JOIN s1.parameters AS s2 JOIN s2.type AS s3 WHERE s3.name = 'Magnetic field' AND s3.units = 'T'
@@ -582,10 +581,10 @@ respectively. We may fix that by applying `DISTINCT`::
582581
`DISTINCT` may be combined with `COUNT`, `AVG`, and `SUM` in order to
583582
make sure not to count the same object more then once::
584583

585-
>>> conditions = {
586-
... "datasets.parameters.type.name": "= 'Magnetic field'",
587-
... "datasets.parameters.type.units": "= 'T'",
588-
... }
584+
>>> conditions = [
585+
... ("datasets.parameters.type.name", "= 'Magnetic field'"),
586+
... ("datasets.parameters.type.units", "= 'T'"),
587+
... ]
589588
>>> query = Query(client, "Investigation",
590589
... conditions=conditions, aggregate="COUNT")
591590
>>> print(query)
@@ -770,9 +769,9 @@ in the `order` argument to :class:`~icat.query.Query`. Let's search
770769
for user sorted by the length of their name, from longest to
771770
shortest::
772771

773-
>>> query = Query(client, "User", conditions={
774-
... "fullName": "IS NOT NULL"
775-
... }, order=[("LENGTH(fullName)", "DESC")])
772+
>>> query = Query(client, "User", conditions=[
773+
... ("fullName", "IS NOT NULL"),
774+
... ], order=[("LENGTH(fullName)", "DESC")])
776775
>>> print(query)
777776
SELECT o FROM User o WHERE o.fullName IS NOT NULL ORDER BY LENGTH(o.fullName) DESC
778777
>>> for user in client.search(query):
@@ -880,13 +879,13 @@ first glance, it has a particular use case::
880879
"""
881880
try:
882881
dataset = client.new("Dataset")
883-
query = Query(client, "Investigation", conditions={
884-
"name": "= '%s'" % inv_name
885-
})
882+
query = Query(client, "Investigation", conditions=[
883+
("name", "= '%s'" % inv_name),
884+
])
886885
dataset.investigation = client.assertedSearch(query)[0]
887-
query = Query(client, "DatasetType", conditions={
888-
"name": "= '%s'" % ds_type
889-
})
886+
query = Query(client, "DatasetType", conditions=[
887+
("name", "= '%s'" % ds_type),
888+
])
890889
dataset.type = client.assertedSearch(query)[0]
891890
dataset.complete = False
892891
dataset.name = ds_name

‎doc/tutorial/search.py‎

Lines changed: 39 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -16,33 +16,33 @@
1616
# --------------------
1717

1818
query = Query(client, "Investigation",
19-
conditions={"name": "= '10100601-ST'"})
19+
conditions=[("name", "= '10100601-ST'")])
2020
print(query)
2121
client.search(query)
2222

2323
# --------------------
2424

2525
query = Query(client, "Investigation",
26-
conditions={"name": "= '10100601-ST'"},
26+
conditions=[("name", "= '10100601-ST'")],
2727
includes=["datasets"])
2828
print(query)
2929
client.search(query)
3030

3131
# --------------------
3232

3333
query = Query(client, "Investigation",
34-
conditions={"LENGTH(title)": "= 18"})
34+
conditions=[("LENGTH(title)", "= 18")])
3535
print(query)
3636
client.search(query)
3737

3838
# --------------------
3939

40-
conditions = {
41-
"investigation.name": "= '10100601-ST'",
42-
"parameters.type.name": "= 'Magnetic field'",
43-
"parameters.type.units": "= 'T'",
44-
"parameters.numericValue": "> 5.0",
45-
}
40+
conditions = [
41+
("investigation.name", "= '10100601-ST'"),
42+
("parameters.type.name", "= 'Magnetic field'"),
43+
("parameters.type.units", "= 'T'"),
44+
("parameters.numericValue", "> 5.0"),
45+
]
4646
query = Query(client, "Dataset",
4747
conditions=conditions, includes=["parameters.type"])
4848
print(query)
@@ -52,9 +52,9 @@
5252

5353
def get_investigation(client, name, visitId=None):
5454
query = Query(client, "Investigation")
55-
query.addConditions({"name": "= '%s'" % name})
55+
query.addConditions([("name", "= '%s'" % name)])
5656
if visitId is not None:
57-
query.addConditions({"visitId": "= '%s'" % visitId})
57+
query.addConditions([("visitId", "= '%s'" % visitId)])
5858
print(query)
5959
return client.assertedSearch(query)[0]
6060

@@ -63,18 +63,19 @@ def get_investigation(client, name, visitId=None):
6363

6464
# --------------------
6565

66-
conditions = {
67-
"datafileCreateTime": [">= '2012-01-01'", "< '2013-01-01'"]
68-
}
66+
conditions = [
67+
("datafileCreateTime", ">= '2012-01-01'"),
68+
("datafileCreateTime", "< '2013-01-01'"),
69+
]
6970
query = Query(client, "Datafile", conditions=conditions)
7071
print(query)
7172
client.search(query)
7273

7374
# --------------------
7475

7576
query = Query(client, "Datafile")
76-
query.addConditions({"datafileCreateTime": ">= '2012-01-01'"})
77-
query.addConditions({"datafileCreateTime": "< '2013-01-01'"})
77+
query.addConditions([("datafileCreateTime", ">= '2012-01-01'")])
78+
query.addConditions([("datafileCreateTime", "< '2013-01-01'")])
7879
print(query)
7980

8081
# --------------------
@@ -99,11 +100,11 @@ def get_investigation(client, name, visitId=None):
99100

100101
# --------------------
101102

102-
conditions = {
103-
"dataset.investigation.name": "= '10100601-ST'",
104-
"type.name": "= 'Magnetic field'",
105-
"type.units": "= 'T'",
106-
}
103+
conditions = [
104+
("dataset.investigation.name", "= '10100601-ST'"),
105+
("type.name", "= 'Magnetic field'"),
106+
("type.units", "= 'T'"),
107+
]
107108
query = Query(client, "DatasetParameter",
108109
conditions=conditions, attributes="numericValue")
109110
print(query)
@@ -120,10 +121,10 @@ def get_investigation(client, name, visitId=None):
120121

121122
# --------------------
122123

123-
conditions = {
124-
"datasets.parameters.type.name": "= 'Magnetic field'",
125-
"datasets.parameters.type.units": "= 'T'",
126-
}
124+
conditions = [
125+
("datasets.parameters.type.name", "= 'Magnetic field'"),
126+
("datasets.parameters.type.units", "= 'T'"),
127+
]
127128
query = Query(client, "Investigation", conditions=conditions)
128129
print(query)
129130
client.search(query)
@@ -136,10 +137,10 @@ def get_investigation(client, name, visitId=None):
136137

137138
# --------------------
138139

139-
conditions = {
140-
"datasets.parameters.type.name": "= 'Magnetic field'",
141-
"datasets.parameters.type.units": "= 'T'",
142-
}
140+
conditions = [
141+
("datasets.parameters.type.name", "= 'Magnetic field'"),
142+
("datasets.parameters.type.units", "= 'T'"),
143+
]
143144
query = Query(client, "Investigation",
144145
conditions=conditions, aggregate="COUNT")
145146
print(query)
@@ -157,9 +158,9 @@ def get_investigation(client, name, visitId=None):
157158

158159
# --------------------
159160

160-
query = Query(client, "User", conditions={
161-
"fullName": "IS NOT NULL"
162-
}, order=[("LENGTH(fullName)", "DESC")])
161+
query = Query(client, "User", conditions=[
162+
("fullName", "IS NOT NULL"),
163+
], order=[("LENGTH(fullName)", "DESC")])
163164
print(query)
164165
for user in client.search(query):
165166
print("%d: %s" % (len(user.fullName), user.fullName))
@@ -196,13 +197,13 @@ def get_dataset(client, inv_name, ds_name, ds_type="raw"):
196197
"""
197198
try:
198199
dataset = client.new("Dataset")
199-
query = Query(client, "Investigation", conditions={
200-
"name": "= '%s'" % inv_name
201-
})
200+
query = Query(client, "Investigation", conditions=[
201+
("name", "= '%s'" % inv_name),
202+
])
202203
dataset.investigation = client.assertedSearch(query)[0]
203-
query = Query(client, "DatasetType", conditions={
204-
"name": "= '%s'" % ds_type
205-
})
204+
query = Query(client, "DatasetType", conditions=[
205+
("name", "= '%s'" % ds_type),
206+
])
206207
dataset.type = client.assertedSearch(query)[0]
207208
dataset.complete = False
208209
dataset.name = ds_name

0 commit comments

Comments
 (0)