diff --git a/include/erlArango.hrl b/include/erlArango.hrl index a590841..ddbb853 100644 --- a/include/erlArango.hrl +++ b/include/erlArango.hrl @@ -5,4 +5,5 @@ -define(Put, <<"PUT">>). -define(Post, <<"POST">>). -define(Head, <<"HEAD">>). +-define(Patch, <<"PATCH">>). -define(Delete, <<"DELETE">>). \ No newline at end of file diff --git a/src/arangoApi/agCollections.erl b/src/arangoApi/agCollections.erl index 9296aa5..0d6e36f 100644 --- a/src/arangoApi/agCollections.erl +++ b/src/arangoApi/agCollections.erl @@ -73,12 +73,12 @@ % 用给定名称创建一个新集合。该请求必须包含具有以下属性的对象。 % 400：如果缺少集合名称，则返回HTTP 400。 % 404：如果集合名称未知，则返回HTTP 404。 -newColl(PoolNameOrSocket, Args) -> - BodyStr = jiffy:encode(Args), +newColl(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/collection">>, [], BodyStr). -newColl(PoolNameOrSocket, Args, WaitForSyncReplication, ForceReplicationFactor) -> - BodyStr = jiffy:encode(Args), +newColl(PoolNameOrSocket, MapData, WaitForSyncReplication, ForceReplicationFactor) -> + BodyStr = jiffy:encode(MapData), Path = <<"/_api/collection?waitForSyncReplication=", (erlang:integer_to_binary(WaitForSyncReplication))/binary, "&forceReplicationFactor=", (erlang:integer_to_binary(ForceReplicationFactor))/binary>>, agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). @@ -166,11 +166,11 @@ collFigures(PoolNameOrSocket, CollName) -> % 该请求必须正文必须包含一个JSON文档，其中至少将集合的分片键属性设置为某些值。 % 响应是一个具有shardId属性的JSON对象，其中将包含负责的分片的ID。 % 注意：此方法仅在群集协调器中可用。 -% eg: args = #{'_key' => testkey, value => 23} +% eg: MapData = #{'_key' => testkey, value => 23} -collResponsibleShard(PoolNameOrSocket, CollName, Args) -> +collResponsibleShard(PoolNameOrSocket, CollName, MapData) -> Path = <<"/_api/collection/", CollName/binary, "/responsibleShard">>, - BodyStr = jiffy:encode(Args), + BodyStr = jiffy:encode(MapData), agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], BodyStr). % 返回集合永久链接的分片 ID @@ -300,7 +300,7 @@ collLoadIndexesIntoMemory(PoolNameOrSocket, CollName) -> Path = <<"/_api/collection/", CollName/binary, "/loadIndexesIntoMemory">>, agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], undefined). -% 更改集合的属性固定链接 +% 更改集合的属性 % PUT /_api/collection/{collection-name}/properties % 路径参数 % collection-name（必填）：集合的名称。 @@ -324,9 +324,9 @@ collLoadIndexesIntoMemory(PoolNameOrSocket, CollName) -> % allowUserKeys：如果设置为true，则允许在文档的_key属性中提供自己的键值。如果设置为 false，那么密钥生成器将独自负责生成密钥，并且在文档的_key属性中提供自己的密钥值被视为错误。 % 注意：除了waitForSync，journalSize和name之外，创建集合后就无法更改集合属性。要重命名集合，必须使用重命名端点。 -collChangeProperties(PoolNameOrSocket, CollName, Args) -> +collChangeProperties(PoolNameOrSocket, CollName, MapData) -> Path = <<"/_api/collection/", CollName/binary, "/properties">>, - BodyStr = jiffy:encode(Args), + BodyStr = jiffy:encode(MapData), agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). % 重命名集合 diff --git a/src/arangoApi/agDbMgr.erl b/src/arangoApi/agDbMgr.erl index 75aaf6c..839a41c 100644 --- a/src/arangoApi/agDbMgr.erl +++ b/src/arangoApi/agDbMgr.erl @@ -40,8 +40,8 @@ curDbList(PoolNameOrSocket) -> % active：一个标志，指示是否应该激活用户帐户。默认值为true。如果设置为false，则用户将无法登录数据库。 % extra：带有额外用户信息的JSON对象。Extra中包含的数据 将为用户存储，但ArangoDB不会进一步解释。 -newDb(PoolNameOrSocket, Args) -> - BodyStr = jiffy:encode(Args), +newDb(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/database">>, [], BodyStr, true). %% 删除现有数据库 diff --git a/src/arangoApi/agDocuments.erl b/src/arangoApi/agDocuments.erl index 5eae686..17685b5 100644 --- a/src/arangoApi/agDocuments.erl +++ b/src/arangoApi/agDocuments.erl @@ -50,4 +50,340 @@ getDocHead(PoolNameOrSocket, CollName, Key, Headers) -> Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, agHttpCli:callAgency(PoolNameOrSocket, ?Head, Path, Headers, undefined). +% 创建文档 +% POST /_api/document/{collection} +% 路径参数 +% 集合（必填）：要在其中创建文档的集合的名称。 +% 查询参数 +% 集合（可选）：集合的名称。这仅是为了向后兼容。在ArangoDB版本<3.0中，URL路径为/ _api / document，并且此查询参数是必需的。这种组合仍然有效，但是建议的方法是在URL路径中指定集合。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% returnNew（可选）：另外 ，在结果的new属性下返回完整的新文档。 +% returnOld（可选）：另外 ，在结果的old属性下返回完整的旧文档。仅在使用覆盖选项时可用。 +% 静音（可选）：如果设置为true，则将返回一个空对象作为响应。创建的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% 覆盖（可选）：如果设置为true，则插入将成为替换插入。如果已经存在具有相同_key的文档，则不会由于违反唯一约束而拒绝新文档，而是将替换旧文档。 +% 请求正文（json） +% 单个文档的JSON表示形式。 +% 从正文中给定的文档创建一个新文档，除非已经有给定_key的文档。如果未提供_key，则会自动生成一个新的唯一_key。 +% 正文中可能始终给定的_id和_rev属性被忽略，URL部分或查询参数集合分别计数。 +% 如果成功创建了文档，则Location标头将包含新创建的文档的路径。该Etag的头字段包含了文档的修订。两者都仅在单个文档的情况下设置。 +% 如果silent未设置为true，则响应的主体包含具有以下属性的JSON对象： +% _id包含新创建的文档的文档标识符 +% _key包含文档密钥 +% _rev包含文档修订版 +% 如果collection参数waitForSync为false，则该调用将在文档被接受后立即返回。直到文档同步到磁盘后，它才会等待。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync也可用于强制将文档创建操作同步到磁盘。因此，waitForSync查询参数可用于强制执行此特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果 未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 返回码 +% 201：如果文档创建成功并且waitForSync为true，则返回 。 +% 202：如果文档创建成功并且waitForSync为false，则返回 。 +% 400：如果正文不包含一个文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果collection指定的collection未知，则返回。在这种情况下，响应主体包含一个错误文档。 +% 409：如果在索引属性中具有相同限定词的文档与现有文档发生冲突并因此违反了该唯一约束，则在单个文档的情况下返回409。在这种情况下，响应主体包含一个错误文档。 +newDocument(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + +newDocument(PoolNameOrSocket, CollName, MapData, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + +% 替换文档 +% PUT /_api/document/{collection}/{key} +% 路径参数 +% 集合（必需）：要在其中替换文档的集合的名称。 +% 密钥（必填）：文档密钥。 +% 查询参数 +% waitForSync（可选）：等待文档已同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，才替换该文档。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 静音（可选）：如果设置为true，则将返回一个空对象作为响应。对于已替换的文档，不会返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID替换文档。 +% 请求正文（json） +% 单个文档的JSON表示形式。 +% 将指定的文档替换为正文中的文档，前提是存在这样的文档并且不违反任何前提条件。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 如果指定了If-Match标头，并且数据库中文档的修订版与给定的修订版不相等，则将违反先决条件。 +% 如果未给出If-Match且ignoreRevs为false，并且主体中存在_rev属性，并且其值与数据库中文档的修订版不匹配，则将违反先决条件。 +% 如果违反了前提条件，则返回HTTP 412。 +% 如果文档存在并且可以更新，则返回HTTP 201或HTTP 202（取决于waitForSync，请参见下文），Etag标头字段包含文档的新修订版，而Location标头包含完整的URL，在该URL下，可以查询文件。 +% 仅限群集：替换文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含更新的文档的已知文档ID，_key 包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档的修订版。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，那么将在结果中的new属性下返回完整的新文档。 +% 如果该文档不存在，则返回HTTP 404，并且响应的正文包含错误文档。 +% 返回码 +% 201：如果成功替换了文档并且waitForSync为true，则返回 。 +% 202：如果成功替换了文档并且waitForSync为false，则返回 。 +% 400：如果正文不包含文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合或文档，则返回。 +% 412：如果违反了前提条件，则返回。该响应还将在_rev 属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +replaceDocument(PoolNameOrSocket, CollName, Key, MapData) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). + +replaceDocument(PoolNameOrSocket, CollName, Key, MapData, Headers, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, Headers, BodyStr). + +% 更新文档 +% PATCH /_api/document/{collection}/{key} +% 路径参数 +% 集合（必填）：要在其中更新文档的集合的名称。 +% 密钥（必填）：文档密钥。 +% 查询参数 +% keepNull（可选）：如果要使用patch命令删除现有属性，则可以将URL查询参数keepNull与false一起使用。这将修改patch命令的行为，以从属性文档中删除属性文件值为null的现有文档。 +% mergeObjects（可选）：控制如果现有文档和修补程序文档中都存在对象（不是数组），是否将合并对象。如果设置为false，则修补程序文档中的值将覆盖现有文档的值。如果设置为true，则对象将被合并。默认值为 true。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，文档才会更新。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 静音（可选）：如果设置为true，则将返回一个空对象作为响应。更新后的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID更新文档。 +% 请求正文（json） +% 文档更新的JSON表示形式作为对象。 +% 部分更新document-id标识的文档。请求的正文必须包含具有要修补的属性的JSON文档（补丁文档）。修补程序文档中的所有属性（如果尚不存在）将被添加到现有文档中，如果存在的话将被覆盖在现有文档中。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 在补丁文档中将属性值设置为null会导致默认情况下为该属性保存null值。 +% 如果指定了If-Match标头，并且数据库中文档的修订版与给定的修订版不相等，则将违反先决条件。 +% 如果未给出If-Match且ignoreRevs为false，并且主体中存在_rev属性，并且其值与数据库中文档的修订版不匹配，则将违反先决条件。 +% 如果违反了前提条件，则返回HTTP 412。 +% 如果文档存在并且可以更新，则返回HTTP 201或HTTP 202（取决于waitForSync，请参见下文），Etag标头字段包含文档的新修订版（双引号），而Location标头包含一个可以查询文档的完整URL。 +% 仅限群集：修补程序文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会以未发现的错误回答 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将更新的文档操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含更新的文档的已知文档ID，_key 包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档的修订版。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，那么将在结果中的new属性下返回完整的新文档。 +% 如果该文档不存在，则返回HTTP 404，并且响应的正文包含错误文档。 +% 返回码 +% 201：如果文档更新成功并且waitForSync为true，则返回 。 +% 202：如果文档更新成功且waitForSync为false，则返回 。 +% 400：如果正文不包含文档的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合或文档，则返回。 +% 412：如果违反了前提条件，则返回。该响应还将在_rev 属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 +updateDocument(PoolNameOrSocket, CollName, Key, MapData) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Patch, Path, [], BodyStr). + +updateDocument(PoolNameOrSocket, CollName, Key, MapData, Headers, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Patch, Path, Headers, BodyStr). + +% 删除文档 +% DELETE /_api/document/{collection}/{key} +% 路径参数 +% 集合（必填）：要在其中删除文档的集合的名称。 +% 密钥（必填）：文档密钥。 +% 查询参数 +% waitForSync（可选）：等待删除操作已同步到磁盘。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% 静音（可选）：如果设置为true，则将返回一个空对象作为响应。对于已删除的文档，不会返回任何元数据。此选项可用于节省一些网络流量。 +% 标头参数 +% If-Match（可选）：您可以使用if-match HTTP标头有条件地根据目标修订版ID删除文档。 +% 如果silent未设置为true，则响应的主体包含一个JSON对象，其中包含有关标识符和修订版的信息。属性 _id包含已删除文档的已知文档ID，_key 包含用于唯一标识给定集合中文档的键，属性_rev包含文档修订版。 +% 如果未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync 的价值真。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 返回码 +% 200：如果文档已成功删除并且waitForSync为true，则返回 。 +% 202：如果文档已成功删除并且waitForSync为false，则返回 。 +% 404：如果找不到集合或文档，则返回。在这种情况下，响应主体包含一个错误文档。 +% 412：如果“如果-match”标头或返回转，并给出找到的文件有不同的版本。响应还将在_rev属性中包含找到的文档的当前修订。此外，将返回属性_id和_key。 + +delDocument(PoolNameOrSocket, CollName, Key) -> + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + +delDocument(PoolNameOrSocket, CollName, Key, Headers, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, "/", (agMiscUtils:toBinary(Key))/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, Headers, undefined). + +% 批量文档操作 +% ArangoDB支持批量处理文档。批量操作影响 单个集合。使用此API变体可使客户端分摊整批文档中的单个请求的开销。不能保证批量操作可以串行执行，ArangoDB 可以并行执行这些操作。这可以转化为大幅的性能提升，尤其是在集群部署中。 +% 如果在处理一个操作期间发生错误，ArangoDB将继续处理其余操作。错误将作为错误文档在响应正文中内联返回（有关更多详细信息，请参见下文）。此外，X-Arango-Error-Codes标头还将包含发生的错误代码及其多重性的映射，例如 1205:10,1210:17，这意味着在10种情况下，错误1205 非法文档句柄；在17种情况下，错误1210 违反了唯一约束。。 +% 通常，批量操作期望输入数组，并且结果主体将包含相同长度的JSON数组。 + + +% 读取单个文档 +% PUT /_api/document/{collection}#get +% 路径参数 +% 集合（必需）：要从中读取文档的集合的名称。 +% 查询参数 +% onlyget（必需）：该参数必须为true，否则将执行替换操作！ +% ignoreRevs（可选）：如果该值为true（默认值）：如果搜索文档包含_rev字段的值，则仅当文档具有相同的修订值时才返回该文档。否则，将返回前提条件失败错误。 +% 返回正文对象中由_key标识的文档。请求的正文必须包含字符串（要查找的_key值）或搜索文档的JSON数组。 +% 搜索文档必须至少包含_key字段的值。一种用于值_rev 可被指定以验证文档是否具有相同的修订值，除非ignoreRevs设置为false。 +% 仅限群集：搜索文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 返回的文档数组包含三个特殊属性：_id包含文档标识符，_key包含唯一标识给定集合中的文档的键，_rev包含修订版。 +% 返回码 +% 200：如果没有发生错误则返回 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 + +getDocuments(PoolNameOrSocket, CollName, KeyOrMapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). + + +% 创建多个文档 +% POST /_api/document/{collection}#multiple +% 路径参数 +% 集合（必填）：要在其中创建文档的集合的名称。 +% 查询参数 +% 集合（可选）：集合的名称。这仅是为了向后兼容。在ArangoDB版本<3.0中，URL路径为/ _api / document，并且此查询参数是必需的。这种组合仍然有效，但是建议的方法是在URL路径中指定集合。 +% waitForSync（可选）：等待文档已同步到磁盘。 +% returnNew（可选）：另外 ，在结果的new属性下返回完整的新文档。 +% returnOld（可选）：另外 ，在结果的old属性下返回完整的旧文档。仅在使用覆盖选项时可用。 +% 静音（可选）：如果设置为true，则将返回一个空对象作为响应。创建的文档将不返回任何元数据。此选项可用于节省一些网络流量。 +% 覆盖（可选）：如果设置为true，则插入将成为替换插入。如果已经存在具有相同_key的文档，则不会由于违反唯一约束而拒绝新文档，而是将替换旧文档。 +% 请求正文（json） +% 要创建的文档数组。 +% 从正文中给定的文档创建新文档，除非已经有给定_key的文档。如果未提供_key，则会自动生成一个新的唯一_key。 +% 结果主体将包含一个长度与输入数组相同的JSON数组，并且每个条目都包含对应输入的运算结果。如果发生错误，则该条目是一个文档，其属性error设置为true，errorCode设置为发生的错误代码。 +% 正文中可能始终给定的_id和_rev属性被忽略，URL部分或查询参数集合分别计数。 +% 如果silent未设置为true，则响应的主体包含具有以下属性的JSON对象数组： +% _id包含新创建的文档的文档标识符 +% _key包含文档密钥 +% _rev包含文档修订版 +% 如果collection参数waitForSync为false，则在文档被接受后，调用将立即返回。直到文档同步到磁盘后，它才会等待。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync也可用于强制将文档创建操作同步到磁盘。因此，waitForSync查询参数可用于强制执行此特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果 未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 应与一些附加的HTTP头的文件已经发生了错误的X阿朗戈-差错代码：被设置，其中包含一个地图，与它们的重数一起发生的错误代码，如在1205：10,1210：17，其意味着在10种情况下发生了错误1205“非法文档句柄”，在17种情况下发生了错误1210“违反唯一约束”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果collection指定的collection未知，则返回。在这种情况下，响应主体包含一个错误文档。 +newDocuments(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + +newDocuments(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + +% 替换多个文件 +% PUT /_api/document/{collection} +% 路径参数 +% 集合（必填）：此URL参数是替换文档的集合的名称。 +% 查询参数 +% waitForSync（可选）：等待新文档同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，才替换该文档。 +% returnOld（可选）：在结果的old属性下还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 请求正文（json） +% 文档数组的JSON表示形式。 +% 用主体中的文档替换指定集合中的多个文档，替换后的文档由 主体文档中的_key属性指定。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 如果ignoreRevs为false，并且正文中的文档中存在_rev属性，并且其值与数据库中相应文档的修订版不匹配，则将违反先决条件。 +% 仅限群集：替换文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会回答“ 未找到”错误。 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 响应的主体包含一个与输入数组长度相同的JSON数组，其中包含有关标识符和替换文档的修订版的信息。在每个条目中，属性 _id包含每个更新文档的已知文档ID， _key包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档修订版。如果发生错误或违反先决条件，则会构建一个错误对象，该错误对象的属性error设置为true，属性 errorCode设置为错误代码。 +% 如果查询参数returnOld为true，则对于每个生成的文档，将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 请注意，如果违反任何前提条件或某些文档发生错误，则返回代码仍为201或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 + +replaceDocuments(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). + +replaceDocuments(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). + +% 更新多个文件 +% PATCH /_api/document/{collection} +% 路径参数 +% 集合（必填）：要在其中更新文档的集合的名称。 +% 查询参数 +% keepNull（可选）：如果要使用patch命令删除现有属性，则可以将URL查询参数keepNull与false一起使用。这将修改patch命令的行为，以从属性文档中删除属性文件值为null的现有文档。 +% mergeObjects（可选）：控制如果现有文档和修补程序文档中都存在对象（不是数组），是否将合并对象。如果设置为false，则修补程序文档中的值将覆盖现有文档的值。如果设置为true，则对象将被合并。默认值为 true。 +% waitForSync（可选）：等待新文档同步到磁盘。 +% ignoreRevs（可选）：默认情况下，或者如果将其设置为true，则忽略给定文档中的_rev属性。如果将其设置为false，则将正文文档中给定的_rev属性作为前提。仅当当前版本是指定的版本时，文档才会更新。 +% returnOld（可选）：在结果的old属性下还返回更改后的文档的完整先前修订。 +% returnNew（可选）： 在结果的new属性下还返回完整的新文档。 +% 请求正文（json） +% 文档更新数组的JSON表示形式是对象。 +% 部分更新文档，要更新的文档由主体对象中的_key属性指定。请求的正文必须包含文档更新的JSON数组，其中包含要修补的属性（补丁文档）。修补程序文档中的所有属性（如果尚不存在）将被添加到现有文档中，如果存在的话将被覆盖在现有文档中。 +% 该_key属性的值以及用作分片键的属性均不得更改。 +% 在补丁文档中将属性值设置为null会导致默认情况下为该属性保存null值。 +% 如果ignoreRevs为false，并且正文中的文档中存在_rev属性，并且其值与数据库中相应文档的修订版不匹配，则将违反先决条件。 +% 仅限群集：修补程序文档可能包含集合的预定义分片键的值。分片键的值被视为提高性能的提示。如果分片键值不正确，ArangoDB可能会以未发现的错误回答 +% 可选地，即使已为整个集合禁用了waitForSync标志，查询参数waitForSync仍可用于强制将文档替换操作同步到磁盘。因此，waitForSync查询参数可用于强制特定操作的同步。要使用此功能，请将waitForSync参数设置为true。如果未指定waitForSync参数或将其设置为 false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync值为true。 +% 响应的主体包含一个与输入数组长度相同的JSON数组，其中包含有关标识符和已更新文档的修订的信息。在每个条目中，属性 _id包含每个更新文档的已知文档ID， _key包含用于唯一标识给定集合中的文档的键，而属性_rev包含新文档修订版。如果发生错误或违反先决条件，则会构建一个错误对象，该错误对象的属性error设置为true，属性 errorCode设置为错误代码。 +% 如果查询参数returnOld为true，则对于每个生成的文档，将在结果的old属性下返回文档的完整先前修订版。 +% 如果查询参数returnNew为true，则对于每个生成的文档，将在结果中的new属性下返回完整的新文档。 +% 请注意，如果违反任何前提条件或某些文档发生错误，则返回代码仍为201或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 201：如果waitForSync为true，并且已处理操作，则返回。 +% 202：如果waitForSync为false并且已处理操作，则返回。 +% 400：如果正文不包含文档数组的有效JSON表示形式，则返回。在这种情况下，响应主体包含一个错误文档。 +% 404：如果找不到集合，则返回。 + +updateDocuments(PoolNameOrSocket, CollName, MapDataList) -> + Path = <<"/_api/document/", CollName/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Patch, Path, [], BodyStr). + +updateDocuments(PoolNameOrSocket, CollName, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Patch, Path, [], BodyStr). + + +% 删除多个文件 +% DELETE /_api/document/{collection} +% 路径参数 +% 集合（必填）：从中删除文档的集合。 +% 查询参数 +% waitForSync（可选）：等待删除操作已同步到磁盘。 +% returnOld（可选）：在结果的old属性下，还返回更改后的文档的完整先前修订。 +% ignoreRevs（可选）：如果设置为true，则忽略选择器中的任何_rev属性。不执行任何修订检查。 +% 请求正文（json） +% 字符串或文档的JSON数组。 +% 请求的主体是一个由文档选择器组成的数组。选择器可以是带键的字符串，带文档标识符的字符串或带_key属性的对象。此API调用从collection中删除所有指定的文档。如果选择器是一个对象并具有_rev属性，则前提是集合中已删除文档的实际修订版是指定的。 +% 响应的主体是一个与输入数组长度相同的数组。对于每个输入选择器，输出都包含一个JSON对象，其中包含有关操作结果的信息。如果未发生错误，则构建一个对象，其中属性_id包含已删除文档的已知文档ID，_key包含用于唯一标识给定集合中的文档的键，而属性_rev包含文档修订版。在发生错误的情况下，与属性的对象错误设置为真和 的errorCode集到的错误代码被构建的。 +% 如果未指定waitForSync参数或将其设置为false，则将应用集合的默认waitForSync行为。该waitForSync查询参数不能用于禁用同步用于具有默认集合waitForSync 的价值真。 +% 如果查询参数returnOld为true，那么将在结果的old属性下返回文档的完整先前修订版。 +% 请注意，如果违反任何先决条件或某些文档发生错误，则返回代码仍为200或202，但是会设置其他HTTP标头X-Arango-Error-Codes，其中包含错误代码的映射，与它们的多重性一起发生，如：1200：17,1205：10，这意味着在17种情况下发生了错误1200“修订冲突”，在10种情况下发生了错误1205“非法文档句柄”。 +% 返回码 +% 200：如果waitForSync为true，则返回。 +% 202：如果waitForSync为false，则返回。 +% 404：如果找不到集合，则返回。在这种情况下，响应主体包含一个错误文档。 + +delDocuments(PoolNameOrSocket, CollName, KeyOrMapDataList) -> + Path = <<"/_api/document/", CollName/binary, "/">>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], BodyStr). +delDocuments(PoolNameOrSocket, CollName, KeyOrMapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/document/", CollName/binary, QueryBinary/binary>>, + BodyStr = jiffy:encode(KeyOrMapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], BodyStr). diff --git a/src/arangoApi/agEdges.erl b/src/arangoApi/agEdges.erl new file mode 100644 index 0000000..b67c5b8 --- /dev/null +++ b/src/arangoApi/agEdges.erl @@ -0,0 +1,26 @@ +-module(agEdges). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/edge.html + +% 边是具有两个附加属性的文档：_from和_to。这些属性是强制性的，并且必须包含边的from和to顶点的文档句柄。 +% 使用常规文档 REST api 进行创建/读取/更新/删除。 +% 读取入站或出站边缘 +% 获得优势 +% GET /_api/edges/{collection-id} +% 路径参数 +% collection-id（必填）：集合的ID。 +% 查询参数 +% 顶点（必填）：起始顶点的ID。 +% 方向（可选）：选择在或出为边缘方向。如果未设置，则返回任何边。 +% 返回以vertex标识的顶点开始或结束的边数组 。 +% 返回码 +% 200：如果找到边缘集合并检索到边缘，则返回。 +% 400：如果请求包含无效参数，则返回。 +% 404：如果未找到边缘集合，则返回。 +getEdges(PoolNameOrSocket, CollName, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/edges/", CollName/binary, QueryBinary/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). diff --git a/src/arangoApi/agGeneralGraphs.erl b/src/arangoApi/agGeneralGraphs.erl new file mode 100644 index 0000000..1522c8d --- /dev/null +++ b/src/arangoApi/agGeneralGraphs.erl @@ -0,0 +1,82 @@ +-module(agGeneralGraphs). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +%% doc_address:https://www.arangodb.com/docs/stable/http/gharial.html + +% 列出图形模块已知的所有图形。 +% GET /_api/gharial +% 列出此数据库中存储的所有图形。 +% 如果模块可用并且可以列出图形，则返回HTTP 200。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% 图表： +% graph：有关新创建的图的信息 +% name：图形名称 +% edgeDefinitions：图形关系的定义数组。每个都有以下类型： +% orphanCollections：其他顶点集合的数组。这些集合中的文档在此图中没有边。 +% numberOfShards：为图中的每个新集合创建的分片数。 +% _id：此图的内部ID值。 +% _rev：此图的修订版。可用于确保不覆盖对该图的并发修改。 +% ReplicationFactor：图形中每个新集合使用的复制因子。 +% isSmart：标记图形是否为SmartGraph（仅限企业版）。 +% smartGraphAttribute：智能图例中的分片属性名称（仅企业版） +getGharial(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/gharial">>, [], undefined). + + +% 在图形模块中创建一个新图形。 +% POST /_api/gharial +% 查询参数 +% waitForSync（可选）：定义请求是否应该等待，直到所有内容都同步到光盘。将更改成功响应代码。 +% 具有以下属性的JSON对象是必需的： +% name：图形名称。 +% edgeDefinitions：图形关系的定义数组。每个都有以下类型： +% orphanCollections：其他顶点集合的数组。这些集合中的文档在此图中没有边。 +% isSmart：定义创建的图形是否应该是智能的。这仅在企业版中有效。 +% options：一个JSON对象，用于定义用于在此图中创建集合的选项。它可以包含以下属性： +% smartGraphAttribute：仅在企业版中有效，如果isSmart为true，则为必需。用于聪明地分割图的顶点的属性名称。此SmartGraph中的每个顶点都必须具有此属性。以后无法修改。 +% numberOfShards：此图中每个集合使用的分片数。以后无法修改。 +% 复制因子：最初为此图创建集合时使用的复制因子。 +% writeConcern：对图中的新集合进行关注。它确定在不同的DBServer上同步每个分片需要多少个副本。如果集群中的副本数量很少，那么分片将拒绝写入。但是，具有足够最新副本的分片写入将同时成功。writeConcern的值 不能大于ReplicationFactor。（仅集群） +% 图的创建需要图的名称和其边缘的定义。 另请参见边缘定义。 +% 如果可以创建图形并且为_graphs集合启用了waitForSync 或在请求中指定了图形，则返回HTTP 201。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息。 +% 如果可以创建图形并且为该_graphs集合禁用了waitForSync，并且未在请求中给出，则返回HTTP 202。响应主体包含已存储的图形配置。 +% error：如果有错误，则标记（true），否则（false）。这个回应是错误的。 +% code：响应代码。 +% graph：有关新创建的图的信息。 +% HTTP 400如果请求的格式错误，则返回。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 403如果您的用户权限不足，则返回。为了创建图，您至少需要具有以下特权： +% Administrate 访问数据库。 +% Read Only 访问此图中使用的每个集合。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +% HTTP 409如果存储图形时发生冲突，则返回。如果已经存储了具有该名称的图形，或者存在一个边缘定义具有相同的边缘集合但在任何其他图形中使用了不同的签名，则可能会发生这种情况 。 +% error：如果有错误，则标记（true），否则（false）。这个回应是真的。 +% code：响应代码。 +% errorNum：发生错误的ArangoDB错误号。 +% errorMessage：为此错误创建的消息。 +newGharial(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/gharial">>, [], BodyStr). + +newGharial(PoolNameOrSocket, MapData, WaitForSync) -> + Path = + case WaitForSync of + true -> + <<"/_api/gharial?waitForSync=true">>; + _ -> + <<"/_api/gharial?waitForSync=false">> + end, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). diff --git a/src/httpCli/agMiscUtils.erl b/src/httpCli/agMiscUtils.erl index fffb3db..6c7445e 100644 --- a/src/httpCli/agMiscUtils.erl +++ b/src/httpCli/agMiscUtils.erl @@ -12,6 +12,7 @@ , getListValue/3 , randomElement/1 , toBinary/1 + , spellQueryPars/1 ]). -spec parseUrl(binary()) -> dbOpts() | {error, invalid_url}. @@ -94,3 +95,13 @@ toBinary(Value) when is_binary(Value) -> Value; toBinary([Tuple | PropList] = Value) when is_list(PropList) and is_tuple(Tuple) -> lists:map(fun({K, V}) -> {toBinary(K), toBinary(V)} end, Value); toBinary(Value) -> term_to_binary(Value). + +-spec spellQueryPars(list()) -> binary(). +spellQueryPars([]) -> + <<>>; +spellQueryPars([{Key, Value}]) -> + <<"?", (toBinary(Key))/binary, "=", (toBinary(Value))/binary>>; +spellQueryPars([{Key, Value} | Tail]) -> + First = <<"?", (toBinary(Key))/binary, "=", (toBinary(Value))/binary>>, + Tail = [<<"&", (toBinary(OtherKey))/binary, "=", (toBinary(OtherValue))/binary>> || {OtherKey, OtherValue} <- Tail], + <>.