ドキュメントの管理
InterSystems IRIS® Data Platform の DocDB は、ObjectScript からの DocDB の操作を可能にするクラス・メソッドを提供します。ObjectScript からの JSON メソッドの呼び出しの詳細は、ドキュメント "JSON の使用" を参照してください。
ドキュメント・データベースの作成または取得
現在のネームスペース内の新規のドキュメント・データベースを作成するには、%CreateDatabase()Opens in a new tab メソッドを呼び出します。
現在のネームスペース内の既存のドキュメント・データベースを取得するには、%GetDatabase()Opens in a new tab メソッドを呼び出します。
ドキュメント・データベースに現在のネームスペース内で一意の名前を割り当てます。名前は修飾 "packagename.docdbname"、未修飾のどちらでもかまいません。データベース名が未修飾の場合は、既定値として ISC.DM パッケージが設定されます。
次の例では、その名前のデータベースが現在のネームスペース内に存在する場合にデータベースを取得します。それ以外の場合は、データベースを作成します。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
次の例では、データベースを作成または取得し、その後、%GetDatabaseDefinition()Opens in a new tab を使用してデータベース定義情報を表示します。これは JSON 動的抽象オブジェクトとして格納されています。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
SET defn = db.%GetDatabaseDefinition()
WRITE defn.%ToJSON()
%SYSTEM.DocDB.GetAllDatabases()Opens in a new tab を使用すると、このネームスペースで定義されているすべてのデータベースの名前を含む JSON 配列を返すことができます。
プロパティの定義 : %CreateProperty()
key:value ペアでドキュメントを取得するには、%CreateProperty()Opens in a new tab を使用して、そのキーのプロパティを定義する必要があります。プロパティを定義すると、ドキュメントが挿入、変更、および削除されたときに、InterSystems IRIS が保持するそのキーのインデックスが自動的に作成されます。プロパティでは、キーのデータ型を指定する必要があります。プロパティは、一意の値 (1) のみの受け入れとして、または非一意 (0) として指定することができます。デフォルトは非一意です。
次の例では、データベースに 2 つのプロパティを割り当てます。その後、データベース定義情報を表示します。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
DO db.%CreateProperty("firstName","%String","$.firstName",0) // creates non-unique property
DO db.%CreateProperty("lastName","%String","$.lastName",1) // create a unique property; an index to support uniqueness is automatically created
WRITE db.%GetDatabaseDefinition().%ToJSON()
ドキュメントの挿入または置換 : %SaveDocument()
ドキュメント ID またはデータ選択条件のいずれかを使用して、データベース内のドキュメントを挿入または置換することができます。
%SaveDocument()Opens in a new tab および %SaveDocumentByKey()Opens in a new tab メソッドは、新規ドキュメントを挿入するか既存のドキュメントを置換することで、ドキュメントを保存します。%SaveDocument() はドキュメント ID でドキュメントを指定し、%SaveDocumentByKey() はキー名とキー値でドキュメントを指定します。
ドキュメント ID を指定しない場合、%SaveDocument() は新しいドキュメントを挿入し、新しいドキュメント ID を生成します。ドキュメント ID を指定した場合は、既存のドキュメントをそのドキュメント ID に置き換えます。ドキュメント ID を指定して、かつそのドキュメントが存在しない場合は、ERROR#5809 例外が生成されます。
ドキュメント・データは、1 つ以上の key:value ペアで構成されます。一意として定義されているキー・プロパティの重複値を指定すると、ERROR#5808 例外が生成されます。
%SaveDocument() メソッドと %SaveDocumentByKey() メソッドは、データベース・ドキュメント・クラスのインスタンスの参照を返します。これは常に、%DocDB.Document のサブクラスです。このメソッドの戻り値のデータ型は %DocDB.Document です。
次の例では、3 つの新しいドキュメントを挿入し、それらにドキュメント ID を割り当てます。その後、ドキュメント ID 2 で識別されるドキュメントの内容全体を、指定された内容に置き換えます。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
WRITE db.%Size(),!
DO db.%CreateProperty("firstName","%String","$.firstName",0)
SET val = db.%SaveDocument({"firstName":"Serena","lastName":"Williams"})
SET val = db.%SaveDocument({"firstName":"Bill","lastName":"Faulkner"})
SET val = db.%SaveDocument({"firstName":"Fred","lastName":"Astare"})
WRITE "Contains ",db.%Size()," documents: ",db.%ToJSON()
SET val = db.%SaveDocument({"firstName":"William","lastName":"Faulkner"},2)
WRITE !,"Contains ",db.%Size()," documents: ",db.%ToJSON()
次の例では、%Id() メソッドを各 %SaveDocument() に連鎖し、挿入または置換された各ドキュメントのドキュメント ID を返します。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
DO db.%CreateProperty("firstName","%String","$.firstName",0)
WRITE db.%SaveDocument({"firstName":"Serena","lastName":"Williams"}).%Id(),!
WRITE db.%SaveDocument({"firstName":"Bill","lastName":"Faulkner"}).%Id(),!
WRITE db.%SaveDocument({"firstName":"Fred","lastName":"Astare"}).%Id(),!
WRITE "Contains ",db.%Size()," documents: ",db.%ToJSON()
WRITE db.%SaveDocument({"firstName":"William","lastName":"Faulkner"},2).%Id(),!
WRITE !,"Contains ",db.%Size()," documents: ",db.%ToJSON()
データベース内のドキュメント数の計算 : %Size()
データベース内のドキュメント数を計算するには、%Size()Opens in a new tab メソッドを呼び出します。
SET doccount = db.%Size()
WRITE doccount
データベース内のドキュメントの取得 : %GetDocument()
%DocumentId によってデータベースから単一のドキュメントを取得するには、次の例に示すように %GetDocument()Opens in a new tab メソッドを呼び出します。
DO db.%GetDocument(2).%ToJSON()
このメソッドは、%Doc プロパティの内容のみを返します。例 :
{"firstName":"Bill","lastName":"Faulkner"}
このメソッドの戻り値の型は %Library.DynamicAbstractObject です。
指定された %DocumentId が存在しない場合、%GetDocument() は、ERROR #5809 例外 : “ロードするオブジェクトがみつかりません” を生成します。
%GetDocumentByKey()Opens in a new tab を使用して、キー値によってデータベースから単一のドキュメントを取得できます。
%FindDocuments() メソッドを使用して、%DocumentId によってデータベースから単一のドキュメントを返すこともできます。例 :
DO db.%FindDocuments(["%DocumentId",2,"="]).%ToJSON()
このメソッドは、ラッパを含む完全な JSON ドキュメントを返します。
{"sqlcode":100,"message":null,"content":[{"%Doc":"{\"firstName\":\"Bill\",\"lastName\":\"Faulkner\"}",
"%DocumentId":2,"%LastModified":"2018-03-06 18:59:02.559"}]}
データベース内のドキュメントの検索 : %FindDocuments()
データベース内の 1 つ以上のドキュメントを検索し、そのドキュメントを JSON として返すには、%FindDocuments()Opens in a new tab メソッドを呼び出します。このメソッドは、3 つのオプションの位置述語 (制約配列、プロジェクション配列、および制限 key:value ペア) の任意の組み合わせを取ります。
位置述語のない次の例は両方とも、データベース内のすべてのドキュメントのすべてのデータを返します。
WRITE db.%FindDocuments().%ToJSON()
WRITE db.%FindDocuments(,,).%ToJSON()
制約述語配列
制約述語構文 ["property","value","operator"] は、一致するドキュメントの内容全体を返します。検索条件には、プロパティ、値、および演算子を配列として指定します。演算子を指定しない場合、既定値として "=" が設定されます。暗黙の AND ロジックを持つ制約述語の配列として、複数の制約を指定できます : [["property","value","operator"],["property2","value2","operator2"]]。制約述語はオプションです。
次の例では、ドキュメント ID が 2 より大きいすべてのドキュメントを返します。
SET result = db.%FindDocuments(["%DocumentId",2,">"])
WRITE result.%ToJSON()
または、複数のメソッドを連鎖させることもできます。
WRITE db.%FindDocuments(["%DocumentId",2,">"]).%ToJSON()
ドキュメントの内容が検索条件と一致する場合は、次のような結果が返されます。
{"sqlcode":100,"message":null,"content":[{"%Doc":"{\"firstName\":\"Fred\",\"lastName\":\"Astare\"}","%DocumentId":"3","%LastModified":"2018-03-05 18:15:30.39"},{"%Doc":"{\"firstName\":\"Ginger\",\"lastName\":\"Rogers\"}","%DocumentId":"4","%LastModified":"2018-03-05 18:15:30.39"}]}
検索条件に一致するドキュメントがない場合は、次の結果が返されます。
{"sqlcode":100,"message":null,"content":[]}
key:value ペアでドキュメントを検索するには、そのキーのドキュメントプロパティを定義しておく必要があります。
IF $SYSTEM.DocDB.Exists("People")
{ SET db = ##class(%DocDB.Database).%GetDatabase("People")}
ELSE {SET db = ##class(%DocDB.Database).%CreateDatabase("People") }
WRITE db.%Size(),!
DO db.%CreateProperty("firstName","%String","$.firstName",0)
SET val = db.%SaveDocument({"firstName":"Fred","lastName":"Rogers"})
SET val = db.%SaveDocument({"firstName":"Serena","lastName":"Williams"})
SET val = db.%SaveDocument({"firstName":"Bill","lastName":"Faulkner"})
SET val = db.%SaveDocument({"firstName":"Barak","lastName":"Obama"})
SET val = db.%SaveDocument({"firstName":"Fred","lastName":"Astare"})
SET val = db.%SaveDocument({"lastName":"Madonna"})
SET result = db.%FindDocuments(["firstName","Fred","="])
WRITE result.%ToJSON()
次の例に示すように、%STARTSWITH、IN、NULL、NOT NULL を含め、さまざまな述語演算子を使用できます。
SET result = db.%FindDocuments(["firstName","B","%STARTSWITH"])
WRITE result.%ToJSON()
SET result = db.%FindDocuments(["firstName","Bill,Fred","IN"])
WRITE result.%ToJSON()
SET result = db.%FindDocuments(["firstName","NULL","NULL"])
WRITE result.%ToJSON()
SET result = db.%FindDocuments(["firstName","NULL","NOT NULL"])
WRITE result.%ToJSON()
プロジェクション述語配列
返されるドキュメントの値の一部のみを返すには、プロジェクションを使用します。オプションのプロジェクション述語 ["prop1","prop2",...] は、対応する値を返すキーを示す配列です。プロジェクション配列でユーザ定義のキーを指定する場合、そのキーのドキュメントプロパティを定義しておく必要があります。
構文 ["property","value","operator"],["prop1","prop2",...] は、一致するドキュメントから指定されたプロパティを返します。
SET result = db.%FindDocuments(["firstName","Bill","="],["%DocumentId","firstName"])
WRITE result.%ToJSON()
制約述語の有無にかかわらず、プロジェクションを指定することができます。したがって、以下の両方とも有効な構文になります。
-
db.%FindDocuments(["property","value","operator"],[prop1,prop2,...]) 制約およびプロジェクション。
-
db.%FindDocuments(,[prop1,prop2,...]) 制約なし、プロジェクション。
制限述語
制限 key:value 述部 {"limit":int} を指定すると、最大で、指定した数の一致するドキュメントのみを返すことができます。
構文 ["property","value","operator"],["prop1","prop2",...],{"limit":int} は、指定された制限数のドキュメントから指定されたプロパティを返します。
SET result = db.%FindDocuments(["firstName","Bill","="],["%DocumentID","firstName"],{"limit":5})
WRITE result.%ToJSON()
この例では、最大 5 つのドキュメントからデータが返されます。
制約述語またはプロジェクション述語の有無にかかわらず、制限を指定することができます。したがって、以下のすべてが有効な構文になります。
-
db.%FindDocuments(["property","value","operator"],,{"limit":int}) 制約、プロジェクションなし、制限。
-
db.%FindDocuments(,[prop1,prop2,...],{"limit":int}) 制約なし、プロジェクション、制限。
-
db.%FindDocuments(,,{"limit":int}) 制約なし、プロジェクションなし、制限。
次の例では、制約なし、プロジェクション、制限を指定します。
WRITE db.%FindDocuments(,["%DocumentId","lastName"],{"limit":3}).%ToJSON()
データベース内のドキュメントのクエリ : %ExecuteQuery()
%ExecuteQuery()Opens in a new tab メソッドを使用して、データベースからドキュメント・データを結果セットとして返すことができます。標準 SQL クエリ SELECT を指定して、FROM 節にデータベース名を指定します。パッケージ名 (スキーマ) なしでデータベース名を作成した場合は、デフォルトの ISC_DM スキーマを指定します。
次の例では、%Doc コンテンツ・データをデータベース内のすべてのドキュメントから結果セットとして取得します。
SET rval=db.%ExecuteQuery("SELECT %Doc FROM ISC_DM.People")
DO rval.%Display()
次の例では、WHERE 節の条件を使用して、ドキュメント ID 値によって取得するドキュメントを制限します。
SET rval=db.%ExecuteQuery("SELECT %DocumentId,%Doc FROM ISC_DM.People WHERE %DocumentId > 2")
DO rval.%Display()
次の例では、WHERE 節の条件を満たすすべてのドキュメントから、%DocumentId および lastName プロパティを取得します。ユーザ定義キーの値を取得するには、そのキーのドキュメント・プロパティを定義しておく必要があります。
SET rval=db.%ExecuteQuery("SELECT %DocumentId,lastName FROM ISC_DM.People WHERE lastName %STARTSWITH 'S'")
DO rval.%Display()
クエリ結果セットの処理の詳細については、"完全な結果セットの返送" または "結果セットからの特定値の返送" を参照してください。
ドキュメントの削除 : %DeleteDocument()
ドキュメント ID またはデータ選択条件のいずれかを使用して、データベースからドキュメントを削除できます。
-
%DeleteDocument()Opens in a new tab メソッドは、ドキュメント ID で指定された 1 つのドキュメントを削除します。
SET val = db.%DeleteDocument(2) WRITE "deleted document = ",val.%ToJSON()
正常に完了した場合、削除されたドキュメントの JSON 値が返されます。失敗した場合、StatusException エラーが返されます。
-
%DeleteDocumentByKey()Opens in a new tab メソッドは、ドキュメントの内容で指定されたドキュメントを削除します。key:value ペアを指定します。
-
%Clear()Opens in a new tab メソッドは、データベース内のすべてのドキュメントを削除し、データベースの oref (オブジェクト参照) を返します (次の例を参照してください)。
SET dboref = db.%Clear() WRITE "database oref: ",dboref,! WRITE "number of documents:",db.%Size()
これにより、次の例に示すように、メソッドを連鎖させることができます。
WRITE db.%Clear().%SaveDocument({"firstName":"Venus","lastName":"Williams"}).%Id(),!