第六章 管理文档 - 插入或替换文档：%SaveDocument()

插入或替换文档：%SaveDocument()

可以使用文档 ID 或数据选择条件在数据库中插入或替换文档。

%SaveDocument()和%SaveDocumentByKey()法保存文档、插入新文档或替换现有文档。 %SaveDocument()通过documentId指定文档； %SaveDocumentByKey() 通过键名和键值指定文档。

如果不指定 documentId，%SaveDocument() 会插入一个新文档并生成一个新 documentId。如果指定 documentId，它将用该 documentId 替换现有文档。如果指定 documentId 但该文档不存在，则会生成 ERROR #5809 异常。

文档数据由一个或多个键：值对组成。如果为定义为唯一的键属性指定重复值，则会生成 ERROR #5808 异常。

%SaveDocument() 和 %SaveDocumentByKey() 方法返回对数据库文档类实例的引用。这始终是 %DocDB.Document 的子类。该方法返回数据类型为%DocDB.Document。

以下示例插入三个新文档并为其分配 documentId。然后，它将 documentId 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()，在插入或替换每个文档时返回每个文档的 documentId：

  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()方法：

  SET doccount = db.%Size()
  WRITE doccount

获取数据库中的文档：%GetDocument()

要通过 %DocumentId 从数据库检索单个文档，请调用 %GetDocument()方法，如以下示例所示：

  DO db.%GetDocument(2).%ToJSON()

此方法仅返回 %Doc 属性内容。例如：

{"firstName":"Bill","lastName":"Faulkner"}

该方法返回类型为%Library.DynamicAbstractObject。

如果指定的 %DocumentId 不存在，%GetDocument() 会生成错误 #5809 异常：“未找到要加载的对象”。

可以使用 %GetDocumentByKey()，按键值从数据库中检索单个文档。

还可以使用 %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"}]}