グローバル参照 API
概要
以下のテーブルに、InterSystems IRIS Python モジュールの gref クラスのメソッドの概要を示します。組み込み Python からこのクラスを使用するには、まず import iris を実行し、次に iris.gref() 関数を使用してグローバルへの参照を取得します。("iris.gref()" を参照してください。)
| グループ | 設定 |
|---|---|
| グローバルのノードでの操作 | data()、get()、getAsBytes()、kill()、set() |
| グローバルの検索 | keys()、order()、orderiter()、query() |
グローバルに関する背景情報は、"グローバルの概要" を参照してください。
data(key)
グローバルのノードにデータが含まれるかどうか、および下位ノードがあるかどうかを確認します。ノードの key は、リストとして渡されます。値が None (または空のリスト) のキーを渡すことは、グローバルのルート・ノードを意味します。
データへのアクセスを試行してエラーが発生する前に、data() を使用して、データが含まれているかどうかノードを調べることができます。ノードが定義されていない (データが含まれていない) 場合、メソッドは 0 を返し、ノードが定義されている (データが含まれている) 場合は 1、ノードは定義されていないが下位ノードがある場合は 10、ノードが定義されていて下位ノードがある場合は 11 を返します。
以下の内容のグローバル ^a があるとします。
^a(2) = "two"
^a(3,1) = "three one"
^a(4) = "four"
^a(4,1) = "four one"
data() を使用して、以下の例のように、グローバルのさまざまなノードをテストできます。
>>> a = iris.gref('^a')
>>> a.data([1])
0
>>> a.data([2])
1
>>> a.data([3])
10
>>> a.data([4])
11
>>> a.data([None])
10
>>> a.data([3,1])
1
モジュロ 2 演算を使用すると、下位ノードがあるかどうかに関係なく、ノードにデータが含まれるかどうかを確認できます。
>>> a.data([3]) % 2
0
>>> a.data([4]) % 2
1
get(key)
グローバルのノードに格納されている値を取得します。ノードの key は、リストとして渡されます。値が None (または空のリスト) のキーを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^a があるとします。
^a(2) = "two"
^a(3,1) = "three one"
^a(4) = "four"
^a(4,1) = "four one"
get() を使用して、以下の例のように、グローバルのさまざまなノードからデータを取得できます。
>>> a = iris.gref('^a')
>>> a.get([2])
'two'
>>> a.get([3,1])
'three one'
また、Python ディクショナリの場合と同様に、ノードの値を直接取得することもできます。dunder メソッド __getitem__() を使用することもできます。
>>> a[3,1]
'three one'
>>> a.__getitem__([3,1])
'three one'
get() を使用して定義されていないノードからデータを取得すると、エラーが発生します。
>>> a.get([5])
Traceback (most recent call last):
File "<input>", line 1, in <module>
KeyError: 'Global Undefined'
データの取得を試行する前に、data() メソッドを使用して、ノードにデータが含まれているかどうかをテストできます。
定義されていないノードから直接、または __getitem__() を使用してデータを取得すると、エラーが発生する代わりに None が返されます。
>>> print(a[5])
None
>>> print(a.__getitem__([5]))
None
"getAsBytes()" も参照してください。
getAsBytes(key)
グローバルのノードに格納されている文字列値を取得して、Python の bytes データ型に変換します。ノードの key は、リストとして渡されます。値が None (または空のリスト) のキーを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^a があるとします。
^a(2) = "two"
^a(3,1) = "three one"
^a(4) = "four"
^a(4,1) = "four one"
getAsBytes() を使用して、以下の例のように、グローバルのさまざまなノードからデータを取得できます。
>>> a = iris.gref('^a')
>>> a.getAsBytes([2])
b'two'
>>> a.getAsBytes([3,1])
b'three one'
getAsBytes() を使用して定義されていないノードからデータを取得すると、エラーが発生します。
>>> a.getAsBytes([5])
Traceback (most recent call last):
File "<input>", line 1, in <module>
KeyError: 'Global Undefined'
データの取得を試行する前に、data() メソッドを使用して、ノードにデータが含まれているかどうかをテストできます。
"get()" も参照してください。
keys(key)
指定されたキーから始めて、グローバルのキーを返します。開始 key はリストとして渡されます。空のリストを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^mlb があるとします。
^mlb = "Major League Baseball"
^mlb("AL") = "American League"
^mlb("AL","Central") = "AL Central"
^mlb("AL","East") = "AL East"
^mlb("AL","East",1) = "Baltimore"
^mlb("AL","East",2) = "Boston"
^mlb("AL","East",3) = "NY Yankees"
^mlb("AL","East",4) = "Tampa Bay"
^mlb("AL","East",5) = "Toronto"
^mlb("AL","West") = "AL West"
^mlb("AL","West",1) = "Houston"
^mlb("AL","West",2) = "LA Angels"
^mlb("AL","West",3) = "Oakland"
^mlb("AL","West",4) = "Seattle"
^mlb("AL","West",5) = "Texas"
^mlb("NL") = "National League"
以下のように、keys() を使用してグローバルのキーを取得し、その値を出力できます。
>>> m = iris.gref('^mlb')
>>> for key in m.keys([]):
... value = m[key]
... print(f'{key} = {value}')
...
['AL'] = American League
['AL', 'Central'] = AL Central
['AL', 'East'] = AL East
['AL', 'East', '1'] = Baltimore
['AL', 'East', '2'] = Boston
['AL', 'East', '3'] = NY Yankees
['AL', 'East', '4'] = Tampa Bay
['AL', 'East', '5'] = Toronto
['AL', 'West'] = AL West
['AL', 'West', '1'] = Houston
['AL', 'West', '2'] = LA Angels
['AL', 'West', '3'] = Oakland
['AL', 'West', '4'] = Seattle
['AL', 'West', '5'] = Texas
['NL'] = National League
開始キーがグローバルのノードとして存在する必要はありません。グローバルはソートされた順序で格納されるため、keys() はソート順序に従って次のノードのキーから始まります。以下に例を示します。
>>> m = iris.gref('^mlb')
>>> for key in m.keys(['AL','North']):
... value = m[key]
... print(f'{key} = {value}')
...
['AL', 'West'] = AL West
['AL', 'West', '1'] = Houston
['AL', 'West', '2'] = LA Angels
['AL', 'West', '3'] = Oakland
['AL', 'West', '4'] = Seattle
['AL', 'West', '5'] = Texas
['NL'] = National League
get() を使用して各ノードの値を取得することもできますが、まず data() を使用して各ノードをテストし、データが含まれていることを確認する必要があります。
order() を使用すると、グローバルの 1 つのレベルでノードが検索されます。
kill(key)
グローバルのノードを削除します (存在する場合)。ノードの key は、リストとして渡されます。この操作により、ノードの下位ノードも削除されます。値が None (または空のリスト) のキーを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^a があるとします。
^a(2) = "two"
^a(3,1) = "three one"
^a(4) = "four"
^a(4,1) = "four one"
kill() を使用して、以下の例のように、グローバルのノードとその下位ノードを削除できます。
>>> a = iris.gref('^a')
>>> a.kill([4])
これで、グローバルの内容は以下のようになります。
^a(2) = "two"
^a(3,1) = "three one"
キーに None を渡すと、グローバル全体が削除されます。
>>> a.kill([None])
order(key)
指定されたキーから始めて、グローバルのそのレベルの次のキーを返します。開始 key はリストとして渡されます。開始キーに続くキーがない場合、order() は None を返します。
以下の内容のグローバル ^mlb があるとします。
^mlb = "Major League Baseball"
^mlb("AL") = "American League"
^mlb("AL","Central") = "AL Central"
^mlb("AL","East") = "AL East"
^mlb("AL","East",1) = "Baltimore"
^mlb("AL","East",2) = "Boston"
^mlb("AL","East",3) = "NY Yankees"
^mlb("AL","East",4) = "Tampa Bay"
^mlb("AL","East",5) = "Toronto"
^mlb("AL","West") = "AL West"
^mlb("AL","West",1) = "Houston"
^mlb("AL","West",2) = "LA Angels"
^mlb("AL","West",3) = "Oakland"
^mlb("AL","West",4) = "Seattle"
^mlb("AL","West",5) = "Texas"
^mlb("NL") = "National League"
order() を使用して、以下の例に示すように、指定されたキーの次のキーを取得できます。
>>> m = iris.gref('^mlb')
>>> m.order(['AL','Central'])
'East'
>>> m.order(['AL','East'])
'West'
>>> m.order(['AL','East',1])
'2'
>>> m.order(['AL','East',2])
'3'
開始キーがグローバルのノードとして存在する必要はありません。グローバルはソートされた順序で格納されるため、order() はソート順序に従って次のノードのキーを返します。以下に例を示します。
>>> m.order(['AL','West',3.5])
'4'
while ループを使用して、特定レベルでグローバルのノードを検索し、戻り値が None になると終了します。開始キーを空の文字列に設定することは、“そのレベルの最初から開始する” ことを意味します。
以下の例では、グローバルの最上位のノードを検索します。
>>> m = iris.gref('^mlb')
>>> key = ""
>>> while True:
... key = m.order([key])
... if key == None:
... break
... print(m[key])
...
American League
National League
以下の例では、グローバルの 3 番目のレベルのノードを検索します。
>>> m = iris.gref('^mlb')
>>> key = ""
>>> while True:
... key = m.order(['AL','East',key])
... if key == None:
... break
... print(m['AL','East',key])
...
Baltimore
Boston
NY Yankees
Tampa Bay
Toronto
必要に応じて while ループを入れ子にしたり、keys() または query() を使用してグローバル全体を検索できます。
orderiter(key)
指定されたキーから始めて次のリーフ・ノードまで、グローバルのキーと値を返します。開始 key はリストとして渡されます。空のリストを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^mlb があるとします。
^mlb = "Major League Baseball"
^mlb("AL") = "American League"
^mlb("AL","Central") = "AL Central"
^mlb("AL","East") = "AL East"
^mlb("AL","East",1) = "Baltimore"
^mlb("AL","East",2) = "Boston"
^mlb("AL","East",3) = "NY Yankees"
^mlb("AL","East",4) = "Tampa Bay"
^mlb("AL","East",5) = "Toronto"
^mlb("AL","West") = "AL West"
^mlb("AL","West",1) = "Houston"
^mlb("AL","West",2) = "LA Angels"
^mlb("AL","West",3) = "Oakland"
^mlb("AL","West",4) = "Seattle"
^mlb("AL","West",5) = "Texas"
^mlb("NL") = "National League"
以下の例は、orderiter() を使用し、ルートから始めて次のリーフ・ノードまで、グローバルを検索します。
>>> m = iris.gref('^mlb')
>>> for (key, value) in m.orderiter([]):
... print(f'{key} = {value}')
...
['AL'] = American League
['AL', 'Central'] = AL Central
開始キーがグローバルのノードとして存在する必要はありません。グローバルはソートされた順序で格納されるため、orderiter() はソート順序に従って次のノードを探します。以下に例を示します。
>>> m = iris.gref('^mlb')
>>> for (key, value) in m.orderiter(['AL','North']):
... print(f'{key} = {value}')
...
['AL', 'West'] = AL West
['AL', 'West', '1'] = Houston
query(key)
指定されたキーから始めてグローバルを検索し、各キーと値を返します。開始 key はリストとして渡されます。空のリストを渡すことは、グローバルのルート・ノードを意味します。
以下の内容のグローバル ^mlb があるとします。
^mlb = "Major League Baseball"
^mlb("AL") = "American League"
^mlb("AL","Central") = "AL Central"
^mlb("AL","East") = "AL East"
^mlb("AL","East",1) = "Baltimore"
^mlb("AL","East",2) = "Boston"
^mlb("AL","East",3) = "NY Yankees"
^mlb("AL","East",4) = "Tampa Bay"
^mlb("AL","East",5) = "Toronto"
^mlb("AL","West") = "AL West"
^mlb("AL","West",1) = "Houston"
^mlb("AL","West",2) = "LA Angels"
^mlb("AL","West",3) = "Oakland"
^mlb("AL","West",4) = "Seattle"
^mlb("AL","West",5) = "Texas"
^mlb("NL") = "National League"
以下の例は、query() を使用し、ルートから始めてグローバルを検索します。
>>> m = iris.gref('^mlb')
>>> for (key, value) in m.query([]):
... print(f'{key} = {value}')
...
['AL'] = American League
['AL', 'Central'] = AL Central
['AL', 'East'] = AL East
['AL', 'East', '1'] = Baltimore
['AL', 'East', '2'] = Boston
['AL', 'East', '3'] = NY Yankees
['AL', 'East', '4'] = Tampa Bay
['AL', 'East', '5'] = Toronto
['AL', 'West'] = AL West
['AL', 'West', '1'] = Houston
['AL', 'West', '2'] = LA Angels
['AL', 'West', '3'] = Oakland
['AL', 'West', '4'] = Seattle
['AL', 'West', '5'] = Texas
['NL'] = National League
開始キーがグローバルのノードとして存在する必要はありません。グローバルはソートされた順序で格納されるため、query() はソート順序に従って次のノードを探します。以下に例を示します。
>>> m = iris.gref('^mlb')
>>> for (key, value) in m.query(['AL','North']):
... print(f'{key} = {value}')
...
['AL', 'West'] = AL West
['AL', 'West', '1'] = Houston
['AL', 'West', '2'] = LA Angels
['AL', 'West', '3'] = Oakland
['AL', 'West', '4'] = Seattle
['AL', 'West', '5'] = Texas
['NL'] = National League
set(key, value)
グローバルのノードを指定された値に設定します。ノードの key はリストとして渡され、value は格納される値です。値が None (または空のリスト) のキーを渡すことは、グローバルのルート・ノードを意味します。
以下の例は、グローバル ^messages への参照を取得し、set() を使用してグローバルのいくつかのノードの値を設定します。
>>> msg = iris.gref('^messages')
>>> msg.set([None], 'list of messages')
>>> msg.set(['greeting',1], 'hello')
>>> msg.set(['greeting',2], 'goodbye')
グローバル ^messages がまだ存在しない場合、以下のようになります。
^messages = "list of messages"
^messages("greeting",1) = "hello"
^messages("greeting",2) = "goodbye"
^messages が既に存在する場合、グローバルに新しい値が追加され、それらのノードの既存のデータは上書きされる可能性があります。設定を試行する前に、data() メソッドを使用して、ノードにデータが既に含まれているかどうかをテストできます。
以下の例のように、Python ディクショナリの場合と同様に、グローバル・ノードを直接設定することもできます。
>>> msg = iris.gref('^messages')
>>> msg['greeting',3] = 'aloha'
これで、グローバル ^messages は以下のようになります。
^messages = "list of messages"
^messages("greeting",1) = "hello"
^messages("greeting",2) = "goodbye"
^messages("greeting",3)="aloha"
