diff --git a/src/arangoApi/agAnalyzers.erl b/src/arangoApi/agAnalyzers.erl new file mode 100644 index 0000000..dc1d5aa --- /dev/null +++ b/src/arangoApi/agAnalyzers.erl @@ -0,0 +1,87 @@ +-module(agAnalyzers). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/analyzers.html + +% 分析仪的HTTP接口 +% 可通过/_api/analyzer端点访问用于管理ArangoSearch Analyzer的RESTful API 。 +% 有关简介以及可用的类型,属性和功能,请参见分析器的描述。 +% 分析仪操作 + +% 根据提供的定义创建一个新的分析器 +% POST /_api/analyzer +% 具有以下属性的JSON对象是必需的: +% name:分析器名称。 +% type:分析器类型。 +% properties:用于配置指定分析器类型的属性。 +% features:在分析器生成的字段上设置的一组功能。默认值为空数组。 +% 根据提供的配置创建一个新的分析器。 +% 返回码 +% 200:名称和定义匹配的分析器已存在。 +% 201:成功创建了新的分析器定义。 +% 400:缺少一个或多个必需参数,或者一个或多个参数无效。 +% 403:用户无权使用此配置创建和分析器。 +newAnalyzer(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/analyzer">>, [], BodyStr). + +% 返回分析器定义 +% GET /_api/analyzer/{analyzer-name} +% 路径参数 +% Analyzer-name(必填):要检索的分析器的名称。 +% 检索指定分析器名称的完整定义。结果对象包含以下属性: +% 名称:分析器名称 +% type:分析仪类型 +% properties:用于配置指定类型的属性 +% 功能:在分析器生成的字段上设置的功能集 +% 返回码 +% 200:分析器定义已成功检索。 +% 404:不存在这种分析器配置。 +getAnalyzer(PoolNameOrSocket, AnalyzerName) -> + Path = <<"/_api/analyzer/", AnalyzerName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + +% 返回可用的分析器定义列表 +% GET /_api/analyzer +% 检索所有分析器定义的数组。结果数组包含具有以下属性的对象: +% 名称:分析器名称 +% type:分析仪类型 +% properties:用于配置指定类型的属性 +% 功能:在分析器生成的字段上设置的功能集 +% 返回码 +% 200:分析器定义已成功检索。 +getAnalyzerList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/analyzer">>, [], undefined). + +% 删除分析仪 +% DELETE /_api/analyzer/{analyzer-name} +% 路径参数 +% Analyzer-name(必填):要删除的分析器的名称。 +% 查询参数 +% 强制(可选):即使正在使用分析仪配置,也应将其删除。默认值为false。 +% 删除由analyzer-name标识的Analyzer配置。 +% 如果成功删除了分析器定义,将返回具有以下属性的对象: +% 错误:假 +% name:删除的分析器的名称 +% 返回码 +% 200:分析仪配置已成功删除。 +% 400:未提供分析器名称,或其他请求参数无效。 +% 403:用户无权删除此分析器配置。 +% 404:不存在这种分析器配置。 +% 409:指定的分析器配置仍在使用中,并且省略了强制或 指定了错误。 + +delAnalyzer(PoolNameOrSocket, AnalyzerName) -> + Path = <<"/_api/analyzer/", AnalyzerName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + +delAnalyzer(PoolNameOrSocket, AnalyzerName, IsForce) -> + Path = + case IsForce of + true -> + <<"/_api/analyzer/", AnalyzerName/binary, "?force=true">>; + _ -> + <<"/_api/analyzer/", AnalyzerName/binary>> + end, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). diff --git a/src/arangoApi/agAqlMod.erl b/src/arangoApi/agAqlMod.erl index 0349dd0..9ba0515 100644 --- a/src/arangoApi/agAqlMod.erl +++ b/src/arangoApi/agAqlMod.erl @@ -12,4 +12,401 @@ % https://www.arangodb.com/docs/stable/http/aql-query-cursor.html % AQL User Functions Management: % https://www.arangodb.com/docs/stable/http/aql-query-cursor.html -% 该模块汇总封装上面所有AQL操作 \ No newline at end of file +% 该模块汇总封装上面所有AQL操作 + +% AQL查询游标的HTTP接口 +% 这是ArangoDB查询的HTTP接口的简介。AQL的结果和简单查询作为游标返回,以便批量处理服务器与客户端之间的通信。每次调用将返回一批文档,并指示当前批是否为最终批。根据查询的不同,结果集中的文档总数可能会或可能不会事先知道。为了释放服务器资源,客户端应在不再需要游标时将其删除。 +% 要执行查询,需要通过HTTP POST请求将查询详细信息从客户端传送到服务器。 + +% 通过HTTP访问游标 +% 创建光标 +% 创建一个游标并返回第一个结果 +% POST /_api/cursor +% 描述查询和查询参数的JSON对象。 +% 具有以下属性的JSON对象是必需的: +% query:包含要执行的查询字符串 +% count:指示是否应在结果的“ count”属性中返回结果集中的文档数。计算“ count”属性将来可能会对某些查询产生性能影响,因此默认情况下此选项处于关闭状态,并且仅在请求时返回“ count”。 +% batchSize:一次往返从服务器传输到客户端的最大结果文档数。如果未设置此属性,则将使用服务器控制的默认值。甲BATCHSIZE的值 0是不允许的。 +% ttl:光标的生存时间(以秒为单位)。在指定的时间后,游标将自动在服务器上删除。这对于确保客户端不完全获取的游标的垃圾回收很有用。如果未设置,则将使用服务器定义的值(默认值:30秒)。 +% cache:用于确定是否应使用AQL查询结果缓存的标志。如果设置为false,那么将跳过查询的任何查询缓存。如果设置为真,这将导致被检查的查询缓存为查询,如果查询缓存模式是上还是需求。 +% memoryLimit:允许查询使用的最大内存数(以字节为单位)。如果设置,则查询将分配过多的内存而失败,并显示错误“超出资源限制”。值为0表示没有内存限制。 +% bindVars:表示绑定参数的键/值对。 +% options:键/值对象,带有用于查询的其他选项。 +% FULLCOUNT:如果设置为真,并在查询中包含LIMIT子句,那么结果将有一个额外的与子属性属性统计 和FULLCOUNT,{ ... , "extra": { "stats": { "fullCount": 123 } } }。该FULLCOUNT属性将包含的文档数量的结果应用于在查询的最后顶层限制之前。它可用于计算符合特定过滤条件的文档数量,但一次只能返回其中的一部分。因此,它类似于MySQL的SQL_CALC_FOUND_ROWS暗示。请注意,设置该选项将禁用一些LIMIT优化,并可能导致处理更多文档,从而使查询运行时间更长。请注意,仅当查询具有顶级LIMIT子句并且在查询中实际使用LIMIT子句时,fullCount属性才可能出现在结果中。 +% maxPlans:限制AQL查询优化器创建的最大计划数。 +% maxWarningCount:限制查询将返回的最大警告数。默认情况下,查询将返回的警告数限制为10,但是可以通过设置此属性来增加或减少该警告数。 +% failOnWarning:设置为true时,查询将引发异常并中止而不产生警告。在开发过程中应使用此选项,以尽早发现潜在问题。当该属性设置为false时,警告将不会传播到异常,并将与查询结果一起返回。还有一个服务器配置选项,--query.fail-on-warning用于设置failOnWarning的默认值,因此不需要在每个查询级别上进行设置。 +% stream:指定true,查询将以流方式执行。查询结果不存储在服务器上,而是动态计算的。注意:只要查询游标存在,长时间运行的查询就需要保持收集锁。设置为false时,查询将立即全部执行。在这种情况下,查询结果要么立即返回(如果结果集足够小),要么存储在arangod实例上,并且可以通过游标API进行访问(相对于ttl)。建议仅在短期运行的查询上使用此选项,或者不使用排他锁(MMFiles上的写锁)。请注意查询选项cache,count并且fullCount不适用于流查询。此外,查询统计信息,警告和概要分析数据仅在查询完成之后才可用。默认值为false +% Optimizer:与查询优化器有关的选项。 +% rules:可以在此属性中放入要包括的或要排除的优化器规则的列表,告诉优化器包括或排除特定的规则。要禁用规则,请在其名称前面加上-,以启用规则,并在其前面加上+。还有一个伪规则all,它匹配所有优化程序规则。-all禁用所有规则。 +% profile:如果设置为true或1,那么如果未从查询缓存提供查询结果,则将在Extra Return属性的子属性配置文件中返回其他查询概要信息。设置为2时,查询将在Extra Return属性的子属性stats.nodes中包含每个查询计划节点的执行统计信息。此外,查询计划在子属性extra.plan中返回。 +% satelliteSyncWait:此Enterprise Edition参数允许配置DBServer有多长时间将查询中涉及的附属集合同步。默认值为60.0(秒)。达到最大时间后,查询将停止。 +% maxRuntime:查询必须在给定的运行时内执行,否则将被终止。该值以秒为单位指定。默认值为0.0(无超时)。 +% maxTransactionSize:事务大小限制(以字节为单位)。仅受RocksDB存储引擎的尊敬。 +% middleCommitSize:最大操作总数,之后将自动执行中间提交。仅受RocksDB存储引擎的尊敬。 +% middleCommitCount:操作之后自动执行中间提交的最大操作数。仅受RocksDB存储引擎的尊敬。 +% skipInaccessibleCollections:AQL查询(尤其是图遍历)将用户没有访问权限的集合视为这些集合为空。您的查询将正常执行,而不是返回禁止的访问错误。这旨在帮助某些用例:一个图包含多个集合,并且不同的用户在该图上执行AQL查询。现在,您可以通过更改用户对集合的访问权限来自然地限制可访问的结果。此功能仅在企业版中可用。 +% 查询详细信息包括查询字符串以及可选的查询选项和绑定参数。这些值需要在POST请求的主体中以JSON表示形式传递。 +% 如果结果集可以由服务器创建,则返回HTTP 201。 +% error:一个标志,指示发生错误(在这种情况下为false) +% code:HTTP状态码 +% result:结果文档数组(如果查询没有结果,则可能为空) +% hasMore:一个布尔值指示符,指示服务器上的游标是否还有更多结果可用 +% count:可用结果文档总数(仅当查询是在设置了count属性的情况下执行的) +% id:在服务器上创建的临时光标的ID(可选,请参见上文) +% extra:一个可选的JSON对象,其统计信息子属性中包含有关查询结果的额外信息。对于数据修改查询, extra.stats子属性将包含已修改的文档数和由于错误而无法修改的文档数(如果指定了ignoreErrors查询选项) +% cached:一个布尔型标志,指示是否从查询缓存提供查询结果。如果从查询缓存提供查询结果,则额外的 return属性将不包含任何stats子属性,也不会包含任何配置文件子属性。 +% 如果JSON格式不正确或请求中缺少查询规范,则返回HTTP 400。 +% 如果JSON格式不正确或请求中缺少查询规范,则服务器将使用HTTP 400进行响应。 +% 响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性: +% error:布尔值标志,指示发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +% 如果查询规范已完成,服务器将处理查询。如果在查询处理期间发生错误,则服务器将使用HTTP 400进行响应。同样,响应的正文将包含有关错误的详细信息。 +% 一个查询错误的列表可以在这里找到。 +% 404:如果查询中访问了不存在的集合,服务器将以HTTP 404进行响应。 +% 405:如果使用了不受支持的HTTP方法,则服务器将以HTTP 405进行响应。 +newAqlCursor(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/cursor">>, [], BodyStr). + + +% 从现有游标返回下一个结果 +% PUT /_api/cursor/{cursor-identifier} +% 路径参数 +% cursor-identifier(必填):光标的名称 +% 如果游标仍然存在,则返回具有以下属性的对象: +% id:光标标识符 +% 结果:当前批次的文档列表 +% hasMore:如果这是最后一批,则为false +% count:如果存在,元素总数 +% 请注意,即使hasMore返回true,下一次调用仍可能不返回任何文档。但是,如果hasMore为false,则光标将被耗尽。一旦hasMore属性的值为 false,客户端就可以停止。 +% 返回码 +% 200:如果成功,服务器将以HTTP 200响应。 +% 400:如果省略了光标标识符,则服务器将使用HTTP 404进行响应。 +% 404:如果找不到具有指定标识符的游标,则服务器将使用HTTP 404进行响应。 +nextAqlCursor(PoolNameOrSocket, CursorId) -> + Path = <<"/_api/cursor/", (agMiscUtils:toBinary(CursorId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], undefined). + +% 删除光标 +% DELETE /_api/cursor/{cursor-identifier} +% 路径参数 +% cursor-identifier(必填):光标的ID +% 删除游标并释放与其关联的资源。 +% 当客户端从服务器上检索所有文档时,游标将在服务器上自动销毁。客户端还可以使用HTTP DELETE请求在任何较早的时间显式销毁游标。游标ID必须作为URL的一部分包含在内。 +% 注意:在服务器控制的特定超时后,服务器还将自动销毁废弃的游标,以避免资源泄漏。 +% 返回码 +% 202:如果服务器知道游标,则返回。 +% 404:如果服务器不知道游标,则返回404。如果在销毁游标后使用了游标,也将返回该值。 +delAqlCursor(PoolNameOrSocket, CursorId) -> + Path = <<"/_api/cursor/", (agMiscUtils:toBinary(CursorId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + +% AQL查询的HTTP接口 +% +% 解释和解析查询 +% ArangoDB有一个HTTP接口,用于语法验证AQL查询。此外,它提供了一个HTTP接口来检索任何有效AQL查询的执行计划。 +% 这两个功能实际上并不执行提供的AQL查询,而只是检查它并返回有关它的元信息。 +% 解释一个AQL查询 +% 解释一个AQL查询并返回有关它的信息 +% POST /_api/explain +% 描述查询和查询参数的JSON对象。 +% 具有以下属性的JSON对象是必需的: +% query:您要解释的查询;如果查询引用了任何绑定变量,则这些变量也必须在属性bindVars中传递。可以在options属性中传递查询的其他选项。 +% bindVars:表示绑定参数的键/值对。 +% options:查询选项 +% allPlans:如果设置为true,将返回所有可能的执行计划。默认值为false,这意味着将仅返回最佳计划。 +% maxNumberOfPlans:允许优化程序生成的可选计划最大数量。将此属性设置为较低的值可以限制优化器的工作量。 +% Optimizer:与查询优化器有关的选项。 +% rules:可以在此属性中放入要包括的或要排除的优化器规则的列表,告诉优化器包括或排除特定的规则。要禁用规则,请在其名称前面加上-,以启用规则,并在其前面加上+。还有一个伪规则all,它匹配所有优化程序规则。-all禁用所有规则。 +% 为了说明如何在服务器上执行AQL查询,可以通过HTTP POST请求将查询字符串发送到服务器。然后,服务器将验证查询并为其创建执行计划。将返回执行计划,但不会执行查询。 +% 服务器返回的执行计划可用于估计查询的可能性能。尽管实际性能将取决于许多不同的因素,但是执行计划通常可以对服务器实际运行查询所需的工作量提供一些粗略的估计。 +% 默认情况下,解释操作将返回查询优化器选择的最佳计划。最佳计划是总估计成本最低的计划。该计划将在响应对象的属性计划中返回。如果在请求中指定了allPlans选项,则结果将包含优化器创建的所有计划。然后将在属性计划中返回计划。 +% 结果还将包含一个属性warnings,它是在优化或执行计划创建期间发生的一系列警告。此外,结果中还包含stats属性以及一些优化程序统计信息。如果allPlans设置为false,则结果将包含可缓存的属性 ,该属性指示如果使用了查询结果缓存,则是否可以将查询结果缓存在服务器上。该缓存时属性不存在allPlans 设置为真。 +% 结果中的每个计划都是一个具有以下属性的JSON对象: +% 节点:计划执行节点的数组。可在此处找到可用节点类型的数组 +% 估计费用:计划的总估计费用。如果有多个计划,优化器将选择总成本最低的计划。 +% collections:查询中使用的一组collections +% rules:优化程序应用的规则数组。可在此处找到可用规则的​​概述 +% variables:查询中使用的变量数组(注意:这可能包含优化器创建的内部变量) +% 返回码 +% 200:如果查询有效,则服务器将使用HTTP 200进行响应,并在响应的plan属性中返回最佳执行计划。如果在请求中设置了选项allPlans,则将在allPlans属性中返回一系列计划。 +% 400:如果请求格式错误或查询包含解析错误,服务器将以HTTP 400响应。响应的正文将包含嵌入在JSON对象中的错误详细信息。如果查询引用任何变量,则忽略绑定变量也会导致HTTP 400错误。 +% 404:如果查询中访问了不存在的集合,服务器将以HTTP 404进行响应。 +explainAqlQuery(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/explain">>, [], BodyStr). + + +% 解析一个AQL查询并返回有关它的信息 +% POST /_api/query +% 具有以下属性的JSON对象是必需的: +% query:要在不执行查询字符串的情况下对其进行验证,可以通过HTTP POST请求将查询字符串传递到服务器。 +% 该端点仅用于查询验证。要实际查询数据库,请参阅/api/cursor。 +% 返回码 +% 200:如果查询有效,服务器将使用HTTP 200进行响应,并在响应的bindVars属性中返回在查询中找到的绑定参数的名称(如果有)。它还将在collections属性中返回查询中使用的collections的数组。如果查询可以成功解析,则返回的JSON 的ast属性将包含查询的抽象语法树表示形式。ast的格式在将来的ArangoDB版本中可能会发生变化,但是可以用来检查ArangoDB如何解释给定查询。请注意,将在不对其应用任何优化的情况下返回抽象语法树。 +% 400:如果请求格式错误或查询包含解析错误,服务器将以HTTP 400响应。响应的正文将包含嵌入在JSON对象中的错误详细信息。 +parseAqlQuery(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/query">>, [], BodyStr). + +% 查询跟踪固定链接 +% ArangoDB具有HTTP接口,用于检索当前正在执行的AQL查询列表和慢速AQL查询列表。为了有意义地使用这些API,需要在执行HTTP请求的数据库中启用查询跟踪。 + +% 返回AQL查询跟踪的配置 +% GET /_api/query/properties +% 返回当前查询跟踪配置。该配置是具有以下属性的JSON对象: +% enabled:如果设置为true,那么将跟踪查询。如果设置为 false,则不会跟踪查询或慢速查询。 +% trackSlowQueries:如果设置为true,则如果慢查询的运行时间超过了slowQueryThreshold中设置的值,则将在慢查询列表中跟踪慢查询 。为了跟踪慢查询, 还必须将enabled属性设置为true。 +% trackBindVars:如果设置为true,那么将跟踪查询中使用的绑定变量。 +% maxSlowQueries:保留在慢速查询列表中的最大慢速查询数。如果慢速查询列表已满,则在发生其他慢速查询时,其中最早的条目将被丢弃。 +% slowQueryThreshold:用于将查询视为慢查询的阈值。当启用慢查询跟踪时,运行时大于或等于此阈值的查询将被放入慢查询列表中。slowQueryThreshold的值以秒为单位指定。 +% maxQueryStringLength:保留在查询列表中的最大查询字符串长度。查询字符串可以有任意长度,如果使用非常长的查询字符串,则可以使用此属性来节省内存。该值以字节为单位指定。 +% 返回码 +% 200:如果成功检索到属性,则返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +getAqlQueryProperties(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/query/properties">>, [], undefined). + + +% 更改AQL查询跟踪的配置 +% PUT /_api/query/properties +% 具有以下属性的JSON对象是必需的: +% enabled:如果设置为true,那么将跟踪查询。如果设置为 false,则不会跟踪查询或慢速查询。 +% trackSlowQueries:如果设置为true,则如果慢查询的运行时间超过了slowQueryThreshold中设置的值,则将在慢查询列表中跟踪慢查询 。为了跟踪慢查询, 还必须将enabled属性设置为true。 +% trackBindVars:如果设置为true,那么将与查询一起跟踪查询中使用的绑定变量。 +% maxSlowQueries:保留在慢速查询列表中的最大慢速查询数。如果慢速查询列表已满,则在发生其他慢速查询时,其中最早的条目将被丢弃。 +% slowQueryThreshold:用于将查询视为慢速的阈值。当启用慢查询跟踪时,运行时大于或等于此阈值的查询将被放入慢查询列表中。slowQueryThreshold的值以秒为单位指定。 +% maxQueryStringLength:要保留在查询列表中的最大查询字符串长度。查询字符串可以有任意长度,如果使用非常长的查询字符串,则可以使用此属性来节省内存。该值以字节为单位指定。 +% 这些属性需要在HTTP请求主体的属性属性中传递。属性必须是JSON对象。 +% 更改属性后,将在HTTP响应中返回当前属性集。 +% 返回码 +% 200:如果属性更改成功,则返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +changeAqlQueryProperties(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, <<"/_api/query/properties">>, [], BodyStr). + + +% 返回当前正在运行的AQL查询的列表 +% GET /_api/query/current +% 返回一个数组,其中包含所选数据库中当前正在运行的AQL查询。每个查询都是一个具有以下属性的JSON对象: +% id:查询的ID +% query:查询字符串(可能被截断) +% bindVars:查询使用的绑定参数值 +% 开始:查询开始的日期和时间 +% runTime:查询的运行时间,直到查询到查询列表为止 +% state:查询的当前执行状态(以字符串形式) +% stream:查询是否使用流游标 +% 返回码 +% 200:可以成功检索查询列表时返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +getAqlQueryCurrent(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/query/current">>, [], undefined). + + +% 返回运行缓慢的AQL查询的列表 +% GET /_api/query/slow +% 返回一个数组,其中包含已完成并超过所选数据库中慢速查询阈值的最后一个AQL查询。可以通过设置查询跟踪属性来控制列表中的最大查询数量maxSlowQueries。可以通过设置查询跟踪属性来调整 将查询视为慢速查询的阈值slowQueryThreshold。 +% 每个查询都是一个具有以下属性的JSON对象: +% id:查询的ID +% query:查询字符串(可能被截断) +% bindVars:查询使用的绑定参数值 +% 开始:查询开始的日期和时间 +% runTime:查询的总运行时间 +% state:查询的当前执行状态(对于慢速查询列表将始终“完成”) +% stream:查询是否使用流游标 +% 返回码 +% 200:可以成功检索查询列表时返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +getAqlQuerySlow(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/query/slow">>, [], undefined). + + +% 清除慢速AQL查询列表 +% DELETE /_api/query/slow +% 清除慢速AQL查询列表 +% 返回码 +% 200:成功清除查询列表后,服务器将以HTTP 200响应。 +% 400:如果请求格式错误,服务器将使用HTTP 400进行响应。 +delAqlQuerySlow(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, <<"/_api/query/slow">>, [], undefined). + + +% 杀死一个AQL查询 +% DELETE /_api/query/{query-id} +% 路径参数 +% query-id(必填):查询的ID。 +% 终止正在运行的查询。查询将在下一个取消点终止。 +% 返回码 +% 200:当执行终止请求并设置查询的终止标志时,查询仍在运行时,服务器将以HTTP 200响应。 +% 400:如果请求格式错误,服务器将使用HTTP 400进行响应。 +% 404:当找不到指定ID的查询时,服务器将以HTTP 404响应。 +killAqlQuery(PoolNameOrSocket, QueryId) -> + Path = <<"/_api/query/", (agMiscUtils:toBinary(QueryId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + +% AQL查询结果缓存的HTTP接口 +% 本节介绍用于控制AQL查询结果缓存的API方法。 + + +% 返回AQL查询结果缓存中存储结果的列表 +% GET /_api/query-cache/entries +% 返回一个数组,其中包含当前存储在所选数据库的查询结果缓存中的AQL查询结果。每个结果都是一个具有以下属性的JSON对象: +% hash:查询结果的哈希值 +% query:查询字符串 +% bindVars:查询的绑定参数。仅当服务器启动时启用了对绑定变量的跟踪时,才显示此属性 +% size:查询结果和绑定参数的大小,以字节为单位 +% 结果:查询结果中的文档/行数 +% 开始:查询存储在缓存中的日期和时间 +% hits:从缓存中提供结果的次数(对于仅存储在缓存中但以后再也不会访问的查询,可以为 0) +% runTime:查询的运行时间 +% dataSources:查询所使用的集合/视图的数组 +% 返回码 +% 200:可以成功检索结果列表时返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +getAqlQueryCaches(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/query-cache/entries">>, [], undefined). + + +% 清除AQL查询结果缓存 +% DELETE /_api/query-cache +% 清除当前数据库的查询结果缓存 +% 返回码 +% 200:成功清除缓存后,服务器将以HTTP 200响应。 +% 400:如果请求格式错误,服务器将使用HTTP 400进行响应。 +clearAqlQueryCaches(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, <<"/_api/query-cache">>, [], undefined). + + +% 返回AQL查询结果缓存的全局配置 +% GET /_api/query-cache/properties +% 返回全局AQL查询结果缓存配置。该配置是具有以下属性的JSON对象: +% mode:AQL查询结果缓存运行的模式。该模式是下列值之一:off,on或demand。 +% maxResults:每个特定于数据库的缓存将存储的最大查询结果数。 +% maxResultsSize:每个数据库特定的缓存将存储的查询结果的最大累积大小。 +% maxEntrySize:每个特定于数据库的缓存将存储的查询的最大单个结果大小。 +% includeSystem:是否将涉及系统集合的查询结果存储在查询结果缓存中。 +% 返回码 +% 200:如果可以成功检索属性,则返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +getAqlQueryCacheProperties(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/query-cache/properties">>, [], undefined). + + +% 更改AQL查询结果缓存的配置 +% PUT /_api/query-cache/properties +% 具有以下属性的JSON对象是必需的: +% mode:AQL查询缓存应以哪种模式运行。可能的值是off,on或demand。 +% maxResults:每个特定于数据库的缓存将存储的最大查询结果数。 +% maxResultsSize:每个数据库特定的缓存将存储的查询结果的最大累积大小。 +% maxEntrySize:每个数据库特定的缓存将存储的查询结果的最大单个大小。 +% includeSystem:是否存储涉及系统集合的查询结果。 +% 更改属性后,将在HTTP响应中返回当前属性集。 +% 注意:更改属性可能会使缓存中的所有结果无效。AQL查询缓存的全局属性。这些属性需要在HTTP请求主体的属性属性中传递。属性必须是具有以下属性的JSON对象: +% 返回码 +% 200:如果属性更改成功,则返回。 +% 400:如果请求格式错误,服务器将以HTTP 400进行响应, +changeAqlQueryCacheProperties(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/query-cache/properties">>, [], BodyStr). + +% 用于AQL用户功能管理的HTTP接口 +% AQL用户功能管理 +% 这是用于管理AQL用户功能的ArangoDB HTTP接口的简介。AQL用户功能是一种使用用户定义的JavaScript代码扩展ArangoDB查询语言(AQL)功能的方法。 + +%有关AQL用户功能及其含义的概述,请参阅“ 扩展AQL”一章。 +%HTTP接口提供用于添加,删除和列出以前注册的AQL用户功能的API。 +%通过此接口管理的所有用户功能将存储在系统集合_aqlfunctions中。此集合中的文档不应直接访问,而只能通过专用接口访问。 + +% 创建AQL用户功能 +% 创建一个新的AQL用户功能 +% POST /_api/aqlfunction +% 具有以下属性的JSON对象是必需的: +% name:用户函数的标准名称。 +% code:函数主体的字符串表示形式。 +% isDeterministic:一个可选的布尔值,用于指示函数结果是否完全确定(函数返回值仅取决于输入值,并且对于具有相同输入的重复调用,返回值相同)。该isDeterministic属性是当前未使用但对于优化可以在以后使用。 +% +% 如果成功,则返回HTTP 200。 +% 如果该功能无效等,则将返回包含详细错误消息的HTTP 400。 +% HTTP 200如果功能已经存在并被调用所取代,则服务器将使用HTTP 200进行响应。 +% error:布尔值标志,指示是否发生错误(在这种情况下为false) +% code:HTTP状态码 +% isNewlyCreated:布尔值标志,指示是否新创建了函数(在这种情况下为false) +% HTTP 201如果服务器可以注册该功能,则服务器将使用HTTP 201进行响应 。 +% error:布尔值标志,指示是否发生错误(在这种情况下为false) +% code:HTTP状态码 +% isNewlyCreated:布尔值标志,指示是否新创建了函数(在这种情况下为true) +% HTTP 400如果JSON格式不正确或请求中缺少必需数据,则服务器将使用HTTP 400进行响应。 +% error:布尔值标志,指示是否发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +newAqlUserFun(PoolNameOrSocket, MapData) -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/aqlfunction">>, [], BodyStr). + +% 删除现有的AQL用户功能 +% DELETE /_api/aqlfunction/{name} +% 路径参数 +% 名称(必填):AQL用户功能的名称。 +% 查询参数 +% 组(可选): - 真:中提供的功能的名称的名称被视为一个命名空间前缀,并在指定的命名空间的所有功能。将被删除。如果没有匹配的字符串,返回的删除函数数可能变为0。 +% 假:中提供的函数名的名称必须是完全限定,包括任何命名空间。如果没有一个与名称匹配,则返回HTTP 404。 +% 删除由name标识的现有AQL用户功能或功能组。 +% HTTP 200如果服务器可以删除该功能,则服务器将使用HTTP 200进行响应 。 +% error:布尔值标志,指示是否发生错误(在这种情况下为false) +% code:HTTP状态码 +% DeleteCount:删除的用户功能的数量,总是1在group设置为false时。设置为true>= 0时的任何数字group +% HTTP 400如果用户功能名称格式错误,则服务器将使用HTTP 400进行响应。 +% error:布尔值标志,指示是否发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +% HTTP 404如果指定的用户用户功能不存在,则服务器将使用HTTP 404进行响应。 +% error:布尔值标志,指示是否发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +delAqlUserFun(PoolNameOrSocket, UserFunName) -> + Path = <<"/_api/aqlfunction/", (agMiscUtils:toBinary(UserFunName))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + + +% 返回注册的AQL用户功能 +% GET /_api/aqlfunction +% 查询参数 +% namespace(可选):从result下的命名空间namespace返回所有已注册的AQL用户函数。 +% 返回所有已注册的AQL用户功能。 +% 该调用将返回一个带有状态代码的JSON数组,以及在result下找到的所有用户函数。 +% HTTP 200成功HTTP 200返回。 +% error:布尔值标志,指示是否发生错误(在这种情况下为false) +% code:HTTP状态码 +% 结果:所有函数,或与命名空间参数匹配的函数 +% name:用户功能的标准名称 +% code:函数体的字符串表示形式 +% isDeterministic:一个可选的布尔值,用于指示函数结果是否完全确定(函数返回值仅取决于输入值,并且对于具有相同输入的重复调用,返回值相同)。该isDeterministic属性是当前未使用但对于优化可以在以后使用。 +% HTTP 400如果用户功能名称格式错误,则服务器将使用HTTP 400进行响应。 +% error:布尔值标志,指示是否发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +getAqlUserFuns(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/aqlfunction">>, [], undefined). + +getAqlUserFuns(PoolNameOrSocket, Namespace) -> + Path = <<"/_api/aqlfunction?namespace=", (agMiscUtils:toBinary(Namespace))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + + + + + + + + + + + diff --git a/src/arangoApi/agAsyncResultHandling.erl b/src/arangoApi/agAsyncResultHandling.erl new file mode 100644 index 0000000..d63f2ce --- /dev/null +++ b/src/arangoApi/agAsyncResultHandling.erl @@ -0,0 +1,123 @@ +-module(agAsyncResultHandling). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/async-results-management.html + +% 用于异步结果管理的HTTP接口 +% 请求执行 +% ArangoDB提供了执行客户端请求的各种方法。客户可以根据其吞吐量,控制流和耐用性要求,在每个请求级别上选择适当的方法。 +% 阻止执行 +% ArangoDB是多线程服务器,允许同时处理多个客户端请求。通信处理和实际工作可以由多个工作线程并行执行。 +% 尽管多个客户端可以连接并并行将其请求发送到ArangoDB,但是客户端可能需要等待其请求被处理。 +% 默认情况下,服务器将完全处理传入的请求,然后将结果返回给客户端。客户端必须等待服务器的响应,然后才能通过连接发送其他请求。对于单线程或非事件驱动的客户端,等待完整的服务器响应可能不是最佳的。 +% 此外,请注意,即使客户端关闭了HTTP连接,在服务器上运行的请求仍将继续,直到完成为止,然后注意客户端不再侦听。因此,关闭连接无助于中止长时间运行的查询!有关详细信息,请参见下面的“ 异步执行”和“结果检索” 以及HttpJobPutCancel下的内容。 +% 忘记并 +% 为了缓解客户端阻止问题,自版本1.4开始使用ArangoDB。提供了一种非阻塞请求的通用机制:如果客户端在请求中添加HTTP标头x-arango-async:true,则ArangoDB会将请求放入内存任务队列中,并向HTTP请求返回HTTP 202(接受)响应客户立即。服务器将异步执行队列中的任务,从而将客户端请求与实际工作分离。 +% 与客户端等待服务器响应相比,这可以提供更高的吞吐量。缺点是发送到客户端的响应始终是相同的(通用HTTP 202),并且客户端此时无法基于实际操作的结果做出决定。实际上,在通用响应到达客户端时,该操作甚至可能尚未执行。因此,客户不能依赖其请求已被成功处理。 +% 服务器上的异步任务队列不会保留,这意味着如果发生崩溃,队列中尚未处理的任务将丢失。但是,客户端将不知道它们是否已被处理。 +% 因此,当客户具有严格的持久性要求或依靠发送操作的结果采取进一步措施时,客户不应发送额外的标头。 +% 排队任务的最大数量由启动选项 --server.maximal-queue-size确定。如果已排队的任务数量超过此数量,则服务器将拒绝该请求,并显示HTTP 500错误。 +% 最后,请注意,无法取消这种火灾并忘记工作,因为稍后您将无法识别它。如果您需要取消请求,请使用“ 异步执行”以及更高版本的“结果检索” 和下面的HttpJobPutCancel。 +% 异步执行和以后的结果检索 +% 通过将HTTP标头x-arango-async:存储添加到请求中,客户端可以指示ArangoDB服务器如上所述异步执行操作,还可以将操作结果存储在内存中以供以后检索。服务器将在HTTP响应标头x-arango-async-id中返回作业ID。客户端可以将此ID与/ _api / job上的HTTP API结合使用,这在本手册中有详细说明。 +% 客户可以通过异步作业API询问ArangoDB服务器,哪些结果准备好检索,哪些没有准备好。客户端还可以通过将原始返回的作业ID传递给异步作业API,以获取已执行的异步作业的原始结果。然后,服务器将返回作业结果,就好像作业已正常执行一样。此外,客户端可以通过其作业ID取消运行异步作业,请参见HttpJobPutCancel。 +% ArangoDB将保留通过x-arango-async:存储 头启动的所有作业结果。仅当客户端明确要求服务器提供特定结果时,才会从服务器中删除结果。 +% 异步作业API还提供了用于垃圾回收的方法,客户端可以使用这些方法来摆脱“旧的”未获取的结果。客户应定期调用此方法,因为ArangoDB不会人为地限制尚未获取的结果的数量。 +% 因此,客户有责任仅存储所需的尽可能多的结果,并尽快获取可用的结果,或至少不时清理未获取的结果。 +% 作业队列和结果仅保存在服务器上的内存中,因此在崩溃时它们将丢失。 +% 取消异步作业 +% 如上所述,可以使用其作业ID取消异步运行的作业。如HttpJobPutCancel中所述,这是通过PUT请求 完成的。 +% 但是,要对幕后发生的事情进行一些解释。首先,一个正在运行的异步查询可以在内部由C ++代码或JavaScript代码执行。例如,CRUD操作直接在C ++中执行,而AQL查询和事务由JavaScript代码执行。作业取消仅适用于JavaScript代码,因为所使用的机制只是在JavaScript线程中触发不可捕获的异常,而该异常将在C ++级别上捕获,从而导致作业的取消。以后将无法检索到任何结果,因为有关该请求的所有数据都将被丢弃。 +% 如果取消在集群的协调器上运行的作业(共享),则仅停止在协调器上运行的代码,集群中可能残留了已经分配给DB-Server的任务,目前无法执行也要取消它们 +% 异步执行和身份验证 +% 如果请求需要身份验证,则在排队之前运行身份验证过程。仅当请求有效凭据且身份验证成功时,该请求才会排队。如果请求不包含有效的凭据,则不会将其排队,但会以与“常规”非排队请求相同的方式立即被拒绝。 + + +% 通过HTTP 管理异步结果 +% 返回异步作业的结果 +% 获取作业结果并将其从队列中删除 +% PUT /_api/job/{job-id} +% 路径参数 +% job-id(必填):异步作业ID。 +% 返回由job-id标识的异步作业的结果。如果服务器上存在异步作业结果,则该结果将从结果列表中删除。这意味着可以为每个job-id调用一次此方法。该方法将返回原始作业结果的标头和正文,以及附加的HTTP标头x-arango-async-job-id。如果存在此标头,则找到作业,并且响应中包含原始作业的结果。如果标题不存在,则找不到作业,并且响应中包含来自作业管理器的状态信息。 +% 返回码 +% 204:如果通过job-id请求的作业仍在待处理(或尚未完成)的作业队列中,则返回。在这种情况下,不会返回x-arango-async-id HTTP标头。 +% 400:如果在请求中未指定作业ID,则返回。在这种情况下,不会返回x-arango-async-id HTTP标头。 +% 404:如果找不到或已经从作业结果列表中删除或提取了作业,则返回404。在这种情况下,不会返回x-arango-async-id HTTP标头。 +getAsyncJobRet(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], undefined). + + +% 取消异步作业 +% PUT /_api/job/{job-id}/cancel +% 路径参数 +% job-id(必填):异步作业ID。 +% 取消由作业ID标识的当前正在运行的作业。请注意,实际取消正在运行的异步作业仍可能需要一些时间。 +% 返回码 +% 200:取消已启动。 +% 400:如果在请求中未指定作业ID,则返回。在这种情况下,不会返回x-arango-async-id HTTP标头。 +% 404:如果找不到或已经从作业结果列表中删除或提取了作业,则返回404。在这种情况下,不会返回x-arango-async-id HTTP标头。 +cancelAsyncJob(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary, "/cancel">>, + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], undefined). + +% 删除异步作业结果 +% DELETE /_api/job/{type}#by-type +% 路径参数 +% type(必填):要删除的作业类型。类型可以是: +% all:删除所有作业结果。当前正在执行或排队的异步作业不会被此调用停止。 +% expired:删除过期的结果。要确定结果的到期状态,请传递戳记查询参数。stamp必须是UNIX时间戳,所有在较低时间戳创建的异步作业结果都将被删除。 +% 实际的工作ID:在这种情况下,调用将删除指定的异步工作的结果。如果作业当前正在执行或排队,则不会中止。 +% 查询参数 +% 标记(可选):UNIX时间戳记,用于指定类型过期时的过期阈值。 +% 删除所有作业结果,过期的作业结果或特定作业的结果。客户可以使用此方法对工作结果进行最终的垃圾收集。 +% 返回码 +% 200:如果删除操作成功执行,则返回。如果未删除任何结果,还将返回此代码。 +% 400:如果未指定type或值无效,则返回。 +% 404:如果type为job-id,但未找到具有指定id的异步作业,则返回404。 +delAsyncJobRet(PoolNameOrSocket, TypeOrJodId, Stamp) -> + Path = + case TypeOrJodId of + <<"expired">> -> + <<"/_api/job/expired?stamp=", (agMiscUtils:toBinary(Stamp))/binary>>; + _ -> + <<"/_api/job/", (agMiscUtils:toBinary(TypeOrJodId))/binary>> + end, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + + +% 返回特定作业的状态 +% GET /_api/job/{job-id} +% 路径参数 +% job-id(必填):异步作业ID。 +% 返回指定作业的处理状态。可以通过查看响应的HTTP响应代码来确定处理状态。 +% 返回码 +% 200:如果已经执行了通过job-id请求的作业,并且已准备好获取其结果,则返回200。 +% 204:如果通过job-id请求的作业仍在待处理(或尚未完成)的作业队列中,则返回。 +% 404:如果找不到或已经从作业结果列表中删除或提取了作业,则返回404。 +getAsyncJobStatus(PoolNameOrSocket, JodId) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(JodId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + + +% 返回具有特定状态的工作结果ID +% GET /_api/job/{type}#by-type +% 路径参数 +% type(必填):要返回的作业类型。类型可以是完成的或待定的。将类型设置为done将使该方法返回可以获取其结果的异步作业的ID。将类型设置为待处理将返回尚未完成的异步作业的ID。 +% 查询参数 +% count(可选):每次调用返回的最大ID数。如果未指定,将使用服务器定义的最大值。 +% 返回具有特定状态(已完成或未决)的异步作业的ID列表。客户端可以使用该列表获取作业系统状态的概述,并在以后检索完成的作业结果。 +% 返回码 +% 200:如果列表可以成功编译,则返回。注意:该列表可能为空。 +% 400:如果未指定type或值无效,则返回。 +getAsyncJobList(PoolNameOrSocket, Type) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(Type))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + +getAsyncJobList(PoolNameOrSocket, Type, Count) -> + Path = <<"/_api/job/", (agMiscUtils:toBinary(Type))/binary, "?count=", (agMiscUtils:toBinary(Count))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + diff --git a/src/arangoApi/agBulkImportExport.erl b/src/arangoApi/agBulkImportExport.erl new file mode 100644 index 0000000..ba9841e --- /dev/null +++ b/src/arangoApi/agBulkImportExport.erl @@ -0,0 +1,162 @@ +-module(agBulkImportExport). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/bulk-imports.html + +% 批量导入的HTTP接口 +% ArangoDB提供了一个HTTP接口,可以一次将多个文档导入一个集合中。这称为批量导入。 +% 上传的数据必须以JSON格式提供。有两种导入数据的机制: +% 自包含的JSON文档:在这种情况下,每个文档都包含所有属性名称和值。在上传的文档中,属性名称可能完全不同 +% 属性名称加上文档数据:在这种情况下,第一个数组必须包含后面文档的属性名称。以下数组仅包含属性值。属性值将按位置映射到属性名称。 +% 两种输入机制的端点地址均为/ _api / import。必须使用HTTP POST请求将数据发送到此URL。要导入的数据必须包含在POST请求的正文中。 +% 该集合的查询参数必须用于指定目标集合导入。将数据导入到不存在的集合中将产生错误。 +% 可以将waitForSync查询参数设置为true,以仅在所有文档都已同步到磁盘后才返回导入。 +% 如果任何上传的文档无效并且无法导入,可以将complete查询参数设置为true,以使整个导入失败。在这种情况下,即使在导入结束时发生故障,导入操作也不会导入任何文档。 +% 如果complete具有除true以外的其他值,则将导入有效文档,而拒绝无效文档,这意味着可能仅导入了一些上载文档。 +% 可以将details查询参数设置为true,以使导入API返回有关无法导入的文档的详细信息。如果details为true,则结果还将包含一个details属性,该属性是详细错误消息的数组。如果将详细信息设置为false或省略,则不会返回任何详细信息。 + +% 导入文档值 +% 从JSON编码的列表中导入文档 +% POST /_api/import#document +% 查询参数 +% 集合(必填):集合名称。 +% fromPrefix(可选):_from属性中值的可选前缀。如果指定,该值将自动添加到每个_from输入值之前。这样就可以仅指定的键_from。 +% toPrefix(可选):_to属性中值的可选前缀。如果指定,该值将自动添加到每个_to输入值之前。这样就可以仅指定的键_to。 +% 覆盖(可选):如果此参数的值为true或yes,则将在导入之前删除集合中的所有数据。请注意,任何现有的索引定义都将保留。 +% waitForSync(可选):等待文档同步到磁盘后再返回。 +% onDuplicate(可选):控制在违反唯一键约束的情况下执行的操作。可能的值为: +% 错误:由于违反唯一键约束,因此不会导入当前文档。这是默认设置。 +% update:这将使用请求中指定的数据更新数据库中的现有文档。请求中不存在的现有文档的属性将被保留。 +% replace:这将用请求中指定的数据替换数据库中的现有文档。 +% ignore:这不会更新现有文档,而只是忽略由唯一键约束冲突引起的错误。 +% 请注意,仅当请求中的导入文档包含_key属性时,update,replace和ignore才起作用。由于次要唯一键约束冲突,更新和 替换也可能失败。 +% 完成(可选):如果设置为true或yes,则如果发生任何错误,将使整个导入失败。否则,即使无法导入某些文档,导入也将继续。 +% details(可选):如果设置为true或yes,结果将包括一个属性,details 其中包含有关无法导入的文档的详细信息。 +% 请求正文(字符串) +% 主体必须由JSON编码的属性值数组组成,每个文档一行。请求的第一行必须是JSON编码的属性名称数组。这些属性名称用于后续各行中的数据。 +% 在由标识的集合中创建文档collection-name。请求正文的第一行必须包含一个JSON编码的属性名称数组。请求正文中的以下所有行都必须包含JSON编码的属性值数组。每行都被解释为一个单独的文档,并且指定的值将映射到在第一标题行中指定的属性名称的数组。 +% 响应是具有以下属性的JSON对象: +% created:导入的文件数。 +% errors:由于错误而未导入的文档数。 +% empty:在输入中找到的空行数(类型documents或只能包含大于零的值auto)。 +% updated:更新/替换的文档数(如果onDuplicate 设置为update或replace)。 +% ignored:失败但被忽略的插入操作数(如果 onDuplicate设置为ignore)。 +% details:如果查询参数details设置为true,则结果将包含一个details属性,该属性是一个数组,其中包含有关无法插入哪些文档的更多详细信息。 +% 返回码 +% 201:如果可以成功导入所有文档,则返回。 +% 400:如果type包含无效值,未collection指定no ,文档编码错误或请求格式错误,则返回。 +% 404:如果collection或导入边的_from或_to属性引用未知集合,则返回。 +% 409:如果导入会触发唯一键冲突,complete则返回,并将 其设置为true。 +% 500:如果服务器无法为没有用户定义密钥的文档自动生成文档密钥(密钥错误),则返回500。 +importFormDocument(PoolNameOrSocket, ListOfList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/import", QueryBinary/binary>>, + BodyStr = jiffy:encode(ListOfList), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + + +% 从JSON 导入文档 +% POST /_api/import#json +% 查询参数 +% 类型(必填):确定如何解释请求的正文。type可以具有以下值: +% documents:使用此类型时,请求正文中的每一行都应为单独的JSON编码的文档。请求主体中的多个JSON对象需要用换行符分隔。 +% list:使用此类型时,请求主体必须包含要导入的单个对象的单个JSON编码数组。 +% auto:如果设置,它将自动确定主体类型( documents或list)。 +% 集合(必填):集合名称。 +% fromPrefix(可选):_from属性中值的可选前缀。如果指定,该值将自动添加到每个_from输入值之前。这样就可以仅指定的键_from。 +% toPrefix(可选):_to属性中值的可选前缀。如果指定,该值将自动添加到每个_to输入值之前。这样就可以仅指定的键_to。 +% 覆盖(可选):如果此参数的值为true或yes,则将在导入之前删除集合中的所有数据。请注意,任何现有的索引定义都将保留。 +% waitForSync(可选):等待文档同步到磁盘:控制在违反唯一键约束的情况下执行的操作。可能的值为: +% 错误:由于违反唯一键约束,因此不会导入当前文档。这是默认设置。 +% update:这将使用请求中指定的数据更新数据库中的现有文档。请求中不存在的现有文档的属性将被保留。 +% replace:这将用请求中指定的数据替换数据库中的现有文档。 +% ignore:这不会更新现有文档,而只是忽略由唯一键约束冲突引起的错误。 +% 请注意,仅当请求中的导入文档包含_key属性时,update,replace和ignore才起作用。由于次要唯一键约束冲突,更新和 替换也可能失败。 +% 完成(可选):如果设置为true或yes,则如果发生任何错误,将使整个导入失败。否则,即使无法导入某些文档,导入也将继续。 +% details(可选):如果设置为true或yes,结果将包括一个属性,details 其中包含有关无法导入的文档的详细信息。 +% 请求正文(字符串) +% 主体必须是JSON编码的对象数组,或者是包含多个以换行符分隔的JSON对象的字符串。 +% 在由标识的集合中创建文档collection-name。文档的JSON表示形式必须作为POST请求的主体传递。请求主体可以由多行组成,每行都是一个独立的JSON对象,也可以是包含子对象的JSON数组。 +% 响应是具有以下属性的JSON对象: +% created:导入的文件数。 +% errors:由于错误而未导入的文档数。 +% empty:在输入中找到的空行数(类型documents或只能包含大于零的值auto)。 +% updated:更新/替换的文档数(如果onDuplicate 设置为update或replace)。 +% ignored:失败但被忽略的插入操作数(如果 onDuplicate设置为ignore)。 +% details:如果查询参数details设置为true,则结果将包含一个details属性,该属性是一个数组,其中包含有关无法插入哪些文档的更多详细信息。 +% 返回码 +% 201:如果可以成功导入所有文档,则返回。 +% 400:如果type包含无效值,未collection指定no ,文档编码错误或请求格式错误,则返回。 +% 404:如果collection或导入边的_from或_to属性引用未知集合,则返回。 +% 409:如果导入会触发唯一键冲突,complete则返回,并将 其设置为true。 +% 500:如果服务器无法为没有用户定义密钥的文档自动生成文档密钥(密钥错误),则返回500。 +importFormJson(PoolNameOrSocket, MapDataList, QueryPars) -> + QueryBinary = agMiscUtils:spellQueryPars(QueryPars), + Path = <<"/_api/import", QueryBinary/binary>>, + BodyStr = jiffy:encode(MapDataList), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + +% 批处理请求的HTTP接口 +% 客户端通常在单独的HTTP请求中向ArangoDB发送单独的操作。这是直接且简单的,但是具有以下缺点:如果连续发出许多小请求,则网络开销可能会很大。 +% 为了缓解此问题,ArangoDB提供了一个批处理请求API,客户端可以使用该API批量向ArangoDB发送多个操作。当客户端必须以较小的正文/有效负载发送许多HTTP请求并且各个请求的结果彼此不依赖时,此方法特别有用。 +% 客户端可以通过向URL / _api / batch处理程序发出多部分HTTP POST请求来使用ArangoDB的批处理API 。如果Content-type为multipart / form-data,则处理程序将接受请求并指定边界字符串。然后,ArangoDB将使用此边界将批处理请求分解为各个部分。这也意味着边界字符串本身不能包含在任何部分中。当ArangoDB将多部分请求分为其各个部分时,它将按顺序处理所有部分,就好像它是一个独立的请求一样。处理完所有零件后,ArangoDB将生成一个多部分HTTP响应,其中每个零件操作结果都包含一个零件。例如,如果您发送包含5个部分的多部分请求,则ArangoDB还将发送包含5个部分的多部分响应。 +% 服务器希望每个零件消息均以以下“头”开头: +% Content-type: application/x-arango-batchpart +% 您可以选择指定Content-Id “标头”以唯一标识每个零件消息。如果已指定,服务器将在其响应中返回Content-Id。否则,服务器将不会发回Content-Id“标头”。服务器将不会验证Content-Id的唯一性。在强制性Content-type和可选Content-Id标头之后,必须紧跟两个Windows换行符(即\ r \ n \ r \ n)。该结构的任何偏差都可能导致零件被拒绝或错误解释。零件请求有效载荷(格式为常规HTTP请求)必须直接遵循两个Windows换行符。 +% 请注意,从 技术上来说,文字Content-type:application / x-arango-batchpart是MIME部分的标头,而HTTP请求(包括其标头)是MIME部分的正文部分。 +% 实际的零件请求应以通常的HTTP方法,被调用的URL和HTTP协议版本开头,后跟任意的HTTP标头。它的主体应遵循通常的\ r \ n \ r \ n 文字。因此,部分请求是常规的HTTP请求,仅嵌入在多部分消息中。 +% 以下示例将发送具有3个单独文档创建操作的批处理。在此示例中使用的边界是 XXXsubpartXXX。 +% ******************************************************************* +% 批处理请求的HTTP接口 改功能不予实现支持 +% ******************************************************************* + +% 用于导出文档的HTTP接口 +% 创建导出光标 +% 使用光标导出集合中的所有文档 +% POST /_api/export +% 查询参数 +% 集合(必填):要导出的集合的名称。 +% 具有以下属性的JSON对象是必需的: +% flush:如果设置为true,则将在导出之前执行WAL刷新操作。刷新操作将开始将文档从WAL复制到集合的数据文件中。刷新后还会有最长为flushWait秒的额外等待时间,以使WAL收集器也可以更改调整后的文档元数据以指向数据文件。默认值为false(即不刷新),因此导出中可能缺少集合中最新插入或更新的文档。 +% flushWait:刷新操作后的最大等待时间(以秒为单位)。默认值为10。仅当flush设置为true时,此选项才有效。 +% count:布尔值标志,指示是否应在结果的“ count”属性中返回结果集中的文档数(可选)。计算“ count”属性将来可能会对性能产生影响,因此默认情况下将关闭此选项,并且仅在请求时才返回“ count”。 +% batchSize:一次往返(从服务器到客户端)要传输的最大结果文档数(可选)。如果未设置此属性,则将使用服务器控制的默认值。 +% limit:可选的限制值,确定要包含在光标中的最大文档数。省略limit属性或将其设置为0将导致不使用任何限制。如果使用限制,则不确定集合中的哪些文档将包含在导出中,哪些文档将排除在外。这是因为集合中没有自然的文档顺序。 +% ttl:光标的可选生存时间(以秒为单位)。在指定的时间后,游标将自动在服务器上删除。这对于确保客户端不完全获取的游标的垃圾回收很有用。如果未设置,将使用服务器定义的值。 +% 限制:包含属性名称数组的对象,返回结果文档时将包含或排除这些属性名称。默认情况下,不指定 限制将返回每个文档的所有属性。 +% 类型:必须根据要使用的类型设置为包含或排除 +% 字段:包含要包含或排除的属性名称的数组。包含或排除属性名称的匹配将仅在顶层完成。目前不支持指定嵌套属性的名称。 +% 对此方法的调用将创建一个游标,其中包含指定集合中的所有文档。与其他数据生成API相比,导出API生成的内部数据结构更轻便,因此这是从集合中检索所有文档的首选方法。 +% 以与/_api/cursorREST API中相似的方式返回文档。如果集合的所有文档都适合第一批,则不会创建任何游标,并且结果对象的hasMore属性将设置为 false。如果不是所有文档都适合第一批文档,则结果对象的hasMore属性将设置为true,并且结果的id属性将包含游标id。 +% 未指定文件退回的顺序。 +% 默认情况下,将仅返回集合中存储在集合数据文件中的那些文档。运行导出时在预写日志(WAL)中存在的文档将不会导出。 +% 为了也导出这些文档,调用者可以在调用导出API或设置flush属性之前发出WAL刷新请求。设置冲洗 选项将在导出之前触发WAL冲洗,以便将文档从WAL复制到集合数据文件。 +% 如果服务器可以创建结果集,则服务器将使用HTTP 201进行响应 。响应的主体将包含带有结果集的JSON对象。 +% 返回的JSON对象具有以下属性: +% 错误:布尔值标志,指示发生错误( 在这种情况下为false) +% code:HTTP状态码 +% result:结果文档数组(如果集合为空,则可能为空) +% hasMore:一个布尔指示器,指示服务器上的光标是否还有更多结果可用 +% count:可用结果文档总数(仅当查询是在设置了count属性的情况下执行的) +% id:在服务器上创建的临时光标的ID(可选,请参见上文) +% 如果JSON格式不正确或请求中缺少查询规范,则服务器将使用HTTP 400进行响应。 +% 响应的主体将包含带有其他错误详细信息的JSON对象。该对象具有以下属性: +% error:布尔值标志,指示发生错误(在这种情况下为true) +% code:HTTP状态码 +% errorNum:服务器错误号 +% errorMessage:描述性错误消息 +% 客户端应该始终尽早删除导出游标结果,因为缠结的导出游标会阻止基础集合被压缩或卸载。默认情况下,未使用的游标将在服务器定义的空闲时间后自动删除,并且客户端可以通过设置ttl值来调整此空闲时间。 +% 注意:群集协调器当前不支持此API。 +% 返回码 +% 201:如果服务器可以创建结果集,则返回。 +% 400:如果JSON表示格式错误或请求中缺少查询规范,则返回。 +% 404:如果查询中访问了不存在的集合,服务器将以HTTP 404进行响应。 +% 405:如果使用了不受支持的HTTP方法,则服务器将以HTTP 405进行响应。 +% 501:如果在群集协调器上调用此API,则服务器将使用HTTP 501进行响应。 +% 如果有更多的数据 然后根据返回的 CousurId 执行newAqlCursor +exportDocuments(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/export?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). \ No newline at end of file diff --git a/src/arangoApi/agIndexes.erl b/src/arangoApi/agIndexes.erl new file mode 100644 index 0000000..da51987 --- /dev/null +++ b/src/arangoApi/agIndexes.erl @@ -0,0 +1,385 @@ +-module(agIndexes). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/indexes.html + +% 索引的HTTP接口 +% 索引 +% 这是对ArangoDB索引的HTTP接口的一般介绍。有各种索引类型的特殊部分。 +% 索引 +% 索引用于允许快速访问文档。对于每个集合,总是有主索引,它是文档关键字(_key属性)的哈希索引 。不能删除或更改该索引。 边缘集合还将具有一个自动创建的边缘索引,该索引无法修改。该索引可通过_from和_to属性快速访问文档。 +% 可以通过定义应建立索引的属性名称来创建大多数用户土地索引。一些索引类型只允许索引一个属性(例如全文索引),而其他索引类型只允许索引多个属性。 +% _id键不支持用户创建的任何索引。 +% 索引句柄 +% 索引句柄唯一地标识数据库中的索引。它是一个字符串,由集合名称和由/分隔的索引标识符组成。如果索引被声明为唯一,那么对索引属性的访问应该很快。如果索引属性仅包含很少的不同值,则性能会降低。 +% 主索引 +% 将自动为每个集合创建一个主索引。它索引文档的主键,这些主键存储在_keysystem属性中。主索引是唯一的,可用于_key和_id属性的查询。无法显式创建或删除主索引。 +% 边缘索引 +% 将自动为边缘集合创建边缘索引。它包含顶点文档之间的连接,并在查询顶点的连接边时调用。无法显式创建或删除边缘索引。边缘索引是唯一的。 +% 哈希索引 +% 哈希索引是未排序的索引,可用于通过相等查找查找单个文档。 +% 跳过列表索引 +% 跳过列表是可用于查找单个文档或文档范围的排序索引。 +% 永久索引 +% 持久索引是可用于查找单个文档或文档范围的排序索引。与其他索引相反,持久索引的内容存储在磁盘上,因此在加载集合时不需要从文档在内存中重建。 +% TTL(生存时间)索引 +% TTL索引可用于自动从集合中删除过期的文档。过期的文档最终将由后台线程删除。 +% 全文索引 +% 全文索引可用于在文档中查找单词或单词前缀。全文索引只能在一个属性上设置,并且将对文档中包含的所有具有该属性文本值的单词进行索引。仅索引(指定)最小长度的单词。使用libicu提供的单词边界分析来完成单词标记化,该分析考虑了服务器启动时提供的所选语言。单词以小写形式索引。该索引支持完全匹配查询(全字)和前缀查询。 +% 索引地址 +% ArangoDB中的所有索引都有唯一的句柄。该索引句柄标识一个索引,并由ArangoDB管理。所有索引都在URI下找到 +% http://server:port/_api/index/index-handle +% 例如:假设索引句柄为demo / 63563528,则该索引的URL为: +% http://localhost:8529/_api/index/demo/63563528 + + +% 使用HTTP使用索引 +% 返回索引 +% GET /_api/index/{index-id} +% 路径参数 +% index-id(必需):索引标识符。 +% 结果是一个描述索引的对象。它至少具有以下属性: +% id:索引的标识符 +% type:索引类型 +% 所有其他属性都取决于类型。例如,某些索引提供 唯一或稀疏标志,而另一些则不提供。一些索引还在结果的selectivityEstimate属性中提供了选择性估计。 +% 返回码 +% 200:如果索引存在,则返回HTTP 200。 +% 404:如果索引不存在,则 返回HTTP 404。 +getIndexInfo(PoolNameOrSocket, IndexId) -> + Path = <<"/_api/index/", (agMiscUtils:toBinary(IndexId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + +% 创建索引 +% 创建一个索引 +% POST /_api/index#general +% 查询参数 +% 集合(必填):集合名称。 +% 请求正文(json) +% 在集合collection中创建一个新索引。期望包含索引详细信息的对象。 +% 必须在 索引详细信息的type属性中指定要创建的索引的类型。根据索引类型,可能需要在请求中指定其他其他属性才能创建索引。 +% 索引要求索引详细信息的fields属性中的被索引属性。根据索引类型,可以为一个或多个属性建立索引。在后一种情况下,需要一个字符串数组。 +% 用户定义的索引不支持索引系统属性_id。使用_id作为索引属性手动创建索引将失败,并显示错误。 +% (可选)索引名称可以在name属性中指定为字符串。索引名称与集合名称具有相同的限制。如果未指定任何值,将自动生成一个值。 +% 某些索引可以创建为唯一或非唯一变体。通过在索引详细信息中指定唯一标志,可以控制大多数索引的唯一性。将其设置为true将创建唯一索引。将其设置为false或忽略unique属性将创建一个非唯一索引。 +% 注意:以下索引类型不支持唯一性,并且对这些类型使用unique属性可能会导致错误: +% 地理索引 +% 全文索引 +% 注意:集群中不支持非分片键上的唯一索引。 +% 可以选择在稀疏变量中创建哈希,跳过列表和持久索引。如果索引详细信息中的sparse属性设置为true,则将创建一个稀疏索引。稀疏索引不会索引未设置任何索引属性或为null的文档。 +% 类型为hash或skiplist的数组索引支持可选的重复数据删除属性。它控制将来自同一文档的重复索引值插入唯一数组索引是否会导致唯一约束错误。默认值为true,因此每个非唯一索引值的单个实例将插入每个文档的索引中。无论此属性的值如何,尝试将值插入到索引中已存在的索引始终将失败。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 400:如果发布了无效的索引说明或使用了目标索引不支持的属性,则返回HTTP 400。 +% 404:如果集合未知,则返回HTTP 404。 +newIndex(PoolNameOrSocket, CollName, MapData) -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr). + + +% 删除索引 +% DELETE /_api/index/{index-id} +% 路径参数 +% index-id(必需):索引ID。 +% 删除带有index-id的索引。 +% 返回码 +% 200:如果可以删除索引,则返回HTTP 200。 +% 404:如果index-id未知,则返回HTTP 404。 +delIndex(PoolNameOrSocket, IndexId) -> + Path = <<"/_api/index/", (agMiscUtils:toBinary(IndexId))/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). + +% 返回集合的所有索引 +% GET /_api/index +% 查询参数 +% 集合(必填):集合名称。 +% 返回一个对象,该对象的属性索引包含给定集合的所有索引描述的数组。在标识符中还可以使用与索引句柄作为键的对象相同的信息。 +% 返回码 +% 200:返回一个JSON对象,其中包含该集合的索引列表。 +getIndexList(PoolNameOrSocket, CollName) -> + Path = <<"/_api/index", CollName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + +% 使用哈希索引 +% 如果存在合适的哈希索引,/_api/simple/by-example则将使用该索引执行示例查询。 + +% 创建一个哈希索引 +% POST /_api/index#hash +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“ hash”。 +% 字段:属性路径的数组。 +% unique:如果为true,则创建一个唯一索引。 +% sparse:如果为true,则创建一个稀疏索引。 +% 重复数据删除:如果为false,则关闭数组值的重复数据删除。 +% 如果不存在,则为集合collection-name创建哈希索引。该调用需要一个包含索引详细信息的对象。 +% 在稀疏索引中,所有不包含至少一个指定索引属性(即field)或在任何指定索引属性中都为null的文档将从索引中排除。如果设置了唯一标志,则不会对此类文档建立索引,也不会将其用于唯一性检查。 +% 在非稀疏索引中,将为这些文档建立索引(对于不存在索引的属性,将使用null值),并且如果设置了唯一标志,则将对它们进行唯一性检查。 +% 注意:集群中不支持非分片键上的唯一索引。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 400:如果集合中已经包含文档,并且您尝试创建唯一哈希索引以使某些文档违反唯一性,则返回HTTP 400。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfHash(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"hash">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + + +% 返回与给定示例匹配的集合的所有文档 +% PUT /_api/simple/by-example +% 此路由不应再使用。从3.4.0版开始,不推荐使用简单查询的所有端点。它们被AQL查询取代。 +% 直到ArangoDB版本3.2.13和3.3.7,此API相当昂贵。一种更轻量的替代方法是使用HTTP Cursor API。从版本3.2.14和3.3.8开始,此性能影响不再是问题,因为API的内部实现已更改。 +% 具有以下属性的JSON对象是必需的: +% collection:要查询的集合的名称。 +% example:示例文档。 +% skip:查询中要跳过的文档数(可选)。 +% limit:要返回的最大文档数。该跳跃 是在之前应用极限的限制。(可选的) +% batchSize:一次往返从服务器传输到客户端的最大结果文档数。如果未设置此属性,则将使用服务器控制的默认值。甲BATCHSIZE的值 0是不允许的。 +% 这将找到与给定示例匹配的所有文档。 +% 返回包含结果的游标,有关详细信息,请参见HTTP Cursor。 +% 返回码 +% 201:查询执行成功返回。 +% 400:如果正文不包含查询的有效JSON表示形式,则返回。在这种情况下,响应主体包含一个错误文档。 +% 404:如果collection指定的collection未知,则返回。在这种情况下,响应主体包含一个错误文档。 + + +% 返回与给定示例匹配的集合的一个文档 +% PUT /_api/simple/first-example +% 此路由不应再使用。从3.4.0版开始,不推荐使用简单查询的所有端点。它们被AQL查询取代。 +% 直到ArangoDB版本3.2.13和3.3.7,此API相当昂贵。一种更轻量的替代方法是使用HTTP Cursor API。从版本3.2.14和3.3.8开始,此性能影响不再是问题,因为API的内部实现已更改。 +% 具有以下属性的JSON对象是必需的: +% collection:要查询的集合的名称。 +% example:示例文档。 +% 这将返回与给定示例匹配的第一个文档。 +% 如果没有文档与示例匹配,则返回包含文档或HTTP 404的结果。 +% 如果集合中有多个文档与指定的示例匹配,则仅返回其中一个文档,并且不确定返回哪个匹配的文档。 +% 返回码 +% 200:成功执行查询后返回。 +% 400:如果正文不包含查询的有效JSON表示形式,则返回。在这种情况下,响应主体包含一个错误文档。 +% 404:如果collection指定的collection未知,则返回。在这种情况下,响应主体包含一个错误文档。 + +% 使用跳过列表索引 +% 如果存在合适的跳过列表索引,则/_api/simple/range其他操作将使用该索引来执行查询。 + + +% 创建一个跳过列表 +% POST /_api/index#skiplist +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“ skiplist”。 +% 字段:属性路径的数组。 +% unique:如果为true,则创建一个唯一索引。 +% sparse:如果为true,则创建一个稀疏索引。 +% 重复数据删除:如果为false,则关闭数组值的重复数据删除。 +% 为集合collection-name创建一个跳过列表索引(如果尚不存在)。该调用需要一个包含索引详细信息的对象。 +% 在稀疏索引中,所有不包含至少一个指定索引属性(即field)或在任何指定索引属性中都为null的文档将从索引中排除。如果设置了唯一标志,则不会对此类文档建立索引,也不会将其用于唯一性检查。 +% 在非稀疏索引中,将为这些文档建立索引(对于不存在索引的属性,将使用null值),并且如果设置了唯一标志,则将对它们进行唯一性检查。 +% 注意:集群中不支持非分片键上的唯一索引。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 400:如果集合中已经包含文档,并且您尝试以存在违反唯一性的文档的方式创建唯一的跳过列表索引,则返回HTTP 400。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfSkipList(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"skiplist">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + +% 使用持久索引 +% 如果存在合适的持久索引,则/_api/simple/range其他操作将使用该索引执行查询。 +% +% 创建一个持久索引 +% POST /_api/index#persistent +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“ persistent”。 +% 字段:属性路径的数组。 +% unique:如果为true,则创建一个唯一索引。 +% sparse:如果为true,则创建一个稀疏索引。 +% 为集合collection-name创建一个持久索引(如果尚不存在)。该调用需要一个包含索引详细信息的对象。 +% 在稀疏索引中,所有不包含至少一个指定索引属性(即field)或在任何指定索引属性中都为null的文档将从索引中排除。如果设置了唯一标志,则不会对此类文档建立索引,也不会将其用于唯一性检查。 +% 在非稀疏索引中,将为这些文档建立索引(对于不存在索引的属性,将使用null值),并且如果设置了唯一标志,则将对它们进行唯一性检查。 +% 注意:集群中不支持非分片键上的唯一索引。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 400:如果集合中已经包含文档,并且您尝试以存在违反唯一性的文档的方式创建唯一的持久索引,那么将返回HTTP 400。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfPersistent(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"persistent">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + +% 使用TTL(生存时间)索引 +% +% 创建一个TTL(生存时间)索引 +% POST /_api/index#ttl +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“ ttl”。 +% fields:一个具有唯一属性路径的数组。 +% expireAfter:文档创建后经过的时间(以秒为单位),之后文档被视为“过期”。 +% 为集合collection-name创建TTL索引(如果尚不存在)。该调用需要一个包含索引详细信息的对象。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 400:如果集合已经包含另一个TTL索引,则返回HTTP 400,因为每个集合最多可以有一个TTL索引。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfTtl(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"ttl">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + +% 使用地理索引 +% +% 创建地理索引 +% POST /_api/index#geo +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“ geo”。 +% 字段:具有一个或两个属性路径的数组。 +% 如果它是一个具有一个属性路径location的数组,那么将使用location作为坐标的路径在所有文档上创建地理空间索引。该属性的值必须是具有至少两个double值的数组。数组必须包含纬度(第一个值)和经度(第二个值)。所有没有属性路径或值不适合的文档都将被忽略。 +% 如果它是具有两个属性路径latitude和经度的数组,则将使用纬度 和经度在所有文档上创建地理空间索引作为路径的纬度和经度。属性纬度和属性经度的值必须加倍。所有没有属性路径或值不适合的文档都将被忽略。 +% geoJson:如果在某个位置上构建了地理空间索引,并且geoJson为true,则数组内的顺序为经度和纬度。这对应于http://geojson.org/geojson-spec.html#positions中描述的格式 +% 在集合collection-name中创建地理空间索引(如果尚不存在)。期望包含索引详细信息的对象。 +% 地理位置索引总是稀疏的,这意味着不包含索引属性或索引属性中具有非数字值的文档将不会被索引。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfGeo(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"geo">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + +%返回给定位置附近集合的所有文档 +%PUT /_api/simple/near +%此路由不应再使用。从3.4.0版开始,不推荐使用简单查询的所有端点。它们被AQL查询取代。 +%具有以下属性的JSON对象是必需的: +%collection:要查询的集合的名称。 +%latitude:坐标的纬度。 +%经度:坐标的经度。 +%distance:如果给定,则用于将距离返回给定坐标的属性键。(可选的)。如果指定,则以米为单位返回距离。 +%skip:查询中要跳过的文档数。(可选的) +%limit:要返回的最大文档数。该跳跃是在之前应用极限的限制。默认值为100。(可选) +%geo:如果给定,则为要使用的地理索引的标识符。(可选的) +%默认值将在给定坐标附近最多找到100个文档。返回的数组根据距离排序,最近的文档在返回数组中排在最前面。如果附近有等距离的文档,则从该组文档中随机选择文档,直到达到限制。 +%为了使用Near运算符,必​​须为集合定义一个地理索引。该索引还定义了哪个属性保存文档的坐标。如果您有多个地理空间索引,则可以使用geo字段来选择特定的索引。 +%返回包含结果的游标,有关详细信息,请参见HTTP Cursor。 +%注意:自ArangoDB 2.6起,不推荐使用近乎简单的查询。在将来的ArangoDB版本中可能会删除此API。使用Near运算符从集合中检索文档的首选方法是使用NEAR函数发出AQL查询,如下所示: +%FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit) +%RETURN doc` +%返回码 +%201:查询执行成功返回。 +%400:如果正文不包含查询的有效JSON表示形式,则返回。在这种情况下,响应主体包含一个错误文档。 +%404:如果collection指定的collection未知,则返回。在这种情况下,响应主体包含一个错误文档。 + +% 查找坐标周围半径内的文档 +% 返回给定半径内集合的所有文档 +% PUT /_api/simple/within +% 此路由不应再使用。从3.4.0版开始,不推荐使用简单查询的所有端点。它们被AQL查询取代。 +% 具有以下属性的JSON对象是必需的: +% collection:要查询的集合的名称。 +% latitude:坐标的纬度。 +% 经度:坐标的经度。 +% radius:最大半径(以米为单位)。 +% distance:如果给定,则用于将距离返回给定坐标的属性键。(可选的)。如果指定,则以米为单位返回距离。 +% limit:要返回的最大文档数。该跳跃是在之前应用极限的限制。默认值为100。(可选) +% geo:如果给定,则为要使用的地理索引的标识符。(可选的) +% 这将找到围绕坐标(纬度,经度)的给定半径内的所有文档。返回的列表按距离排序。 +% 为了使用内部运算符,必​​须为集合定义一个地理索引。该索引还定义了哪个属性保存文档的坐标。如果您有多个地理空间索引,则可以使用geo字段来选择特定的索引。 +% 返回包含结果的游标,有关详细信息,请参见HTTP Cursor。 +% 注意:从ArangoDB 2.6开始不推荐使用内部简单查询。在将来的ArangoDB版本中可能会删除此API。使用Near运算符从集合中检索文档的首选方法是使用WITHIN函数发出AQL查询,如下所示: +% FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName) +% RETURN doc +% 返回码 +% 201:查询执行成功返回。 +% 400:如果正文不包含查询的有效JSON表示形式,则返回。在这种情况下,响应主体包含一个错误文档。 +% 404:如果collection指定的collection未知,则返回。在这种情况下,响应主体包含一个错误文档。 + +% 全文 +% 如果存在全文索引, /_api/simple/fulltext则将使用该索引执行指定的全文查询。 +% +% 创建全文索引 +% +% POST /_api/index#fulltext +% 查询参数 +% 集合(必填):集合名称。 +% 具有以下属性的JSON对象是必需的: +% 类型:必须等于“fulltext”。 +% 字段:属性名称的数组。当前,数组仅限于一个属性。 +% minLength:要索引的单词的最小字符长度。如果未指定,则默认为服务器定义的值。因此,建议在创建索引时显式设置此值。 +% 为集合collection-name创建全文索引(如果尚不存在)。该调用需要一个包含索引详细信息的对象。 +% 返回码 +% 200:如果索引已经存在,则返回HTTP 200。 +% 201:如果索引尚不存在并且可以创建,则 返回HTTP 201。 +% 404:如果集合名称未知,则返回HTTP 404。 +newIndexOfFulltext(PoolNameOrSocket, CollName, MapData) -> + case MapData of + #{<<"type">> := <<"fulltext">>} -> + Path = <<"/_api/index?collection=", CollName/binary>>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, Path, [], BodyStr); + _ -> + {error, param} + end. + +% 全文索引查询 +% 通过全文查询返回集合的文档 +% PUT /_api/simple/fulltext +% 此路由不应再使用。从3.4.0版开始,不推荐使用简单查询的所有端点。它们被AQL查询取代。 +% 具有以下属性的JSON对象是必需的: +% collection:要查询的集合的名称。 +% attribute:包含文本的属性。 +% 查询:全文查询。请参阅全文查询 以获取详细信息。 +% skip:查询中要跳过的文档数(可选)。 +% limit:要返回的最大文档数。该跳跃 是在之前应用极限的限制。(可选的) +% index:要使用的全文索引的标识符。 +% 这将发现从集合匹配指定的全文查询的所有文档的查询。 +% 为了使用全文运算符,必​​须为集合和指定的属性定义全文索引。 +% 返回包含结果的游标,有关详细信息,请参见HTTP Cursor。 +% 注意:从ArangoDB 2.6起不推荐使用全文本简单查询。在将来的ArangoDB版本中可能会删除此API。使用Near运算符从集合中检索文档的首选方法是使用FULLTEXT AQL函数发出AQL查询 ,如下所示: +% FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit) +% RETURN doc +% 返回码 +% 201:查询执行成功返回。 +% 400:如果正文不包含查询的有效JSON表示形式,则返回。在这种情况下,响应主体包含一个错误文档。 +% 404:如果collection指定的collection未知,则返回。在这种情况下,响应主体包含一个错误文档。 + + + diff --git a/src/arangoApi/agSimpleQueries.erl b/src/arangoApi/agSimpleQueries.erl new file mode 100644 index 0000000..8869b5f --- /dev/null +++ b/src/arangoApi/agSimpleQueries.erl @@ -0,0 +1,9 @@ +-module(agSimpleQueries). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/simple-query.html + +% 从版本3.4.0开始不推荐使用简单查询API。这些端点不应再使用。它们被AQL查询取代。 + diff --git a/src/arangoApi/agTransactions.erl b/src/arangoApi/agTransactions.erl new file mode 100644 index 0000000..73972c5 --- /dev/null +++ b/src/arangoApi/agTransactions.erl @@ -0,0 +1,7 @@ +-module(agTransactions). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/transaction.html + diff --git a/src/arangoApi/agViews.erl b/src/arangoApi/agViews.erl new file mode 100644 index 0000000..6134889 --- /dev/null +++ b/src/arangoApi/agViews.erl @@ -0,0 +1,200 @@ +-module(agViews). +-include("erlArango.hrl"). + +-compile([export_all, nowarn_export_all]). + +% doc_address:https://www.arangodb.com/docs/stable/http/views.html + +% ArangoSearch视图 +% 创建一个ArangoSearch视图 +% POST /_api/view#arangosearch +% 具有以下属性的JSON对象是必需的: +% name:视图的名称。 +% type:视图的类型。必须等于“ arangosearch”。此选项是不变的。 +% links:期望一个对象,其属性键为要链接的集合的名称,链接属性为属性值。有关 详细信息,请参见 ArangoSearch查看链接属性。 +% primarySort:可以定义一个主要排序顺序以启用AQL优化。如果查询遍历View的所有文档,想要按属性值对它们进行排序,并且要按(最左边的)字段对它们进行排序,以及它们的排序方向与primarySort定义匹配,则SORT操作将被优化。此选项是不变的。 +% 需要一个对象数组,每个对象指定一个字段(属性路径)和一个排序方向("asc升序,"desc"降序): [ { "field": "attr", "direction": "asc"}, … ] +% cleanupIntervalStep:在删除ArangoSearch数据目录中的未使用文件之间至少等待这么多次提交(默认值:2,以禁用使用:0)。对于合并策略经常合并段的情况(即大量的commit + consolidate),较低的值将导致浪费大量磁盘空间。对于合并策略很少合并段(即,很少的插入/删除)的情况,较高的值将影响性能,而不会带来任何额外的好处。 +% 背景: 每次执行“提交”或“合并”操作时,都会在磁盘上创建View内部数据结构的新状态。一旦不再有任何用户可用,就会释放旧状态/快照。但是,释放状态/快照的文件保留在磁盘上,只能通过“清理”操作将其删除。 +% commitIntervalMsec:在提交View数据存储更改和使文档对查询可见之前,至少要等待这么多毫秒(默认值:1000,禁用使用:0)。对于插入/更新很多的情况,较低的值(直到提交)将导致索引无法解决这些问题,并且内存使用量将继续增长。对于插入/更新次数很少的情况,较高的值将影响性能并浪费每个提交调用的磁盘空间,而没有任何其他好处。 +% 背景: 对于数据检索,ArangoSearch视图遵循“最终一致”的概念,即,最终ArangoDB中的所有数据将通过相应的查询表达式进行匹配。引入了ArangoSearch View“提交”操作的概念,以控制直到相应的查询表达式实际反映出文档添加/删除的时间的上限。一旦“提交”操作完成,在“提交”操作开始之前添加/删除的所有文档将由后续ArangoDB事务中调用的查询反映,正在进行的ArangoDB事务仍将继续返回可重复读取状态。 +% integrationIntervalMsec:在应用'consolidationPolicy'合并View数据存储与可能释放文件系统上的空间之间至少等待这么多毫秒(默认值:10000,禁用使用:0)。对于存在大量数据修改操作的情况,较高的值可能会使数据存储区消耗更多的空间和文件句柄。对于少量数据修改操作的情况,较低的值将影响性能,因为没有可用于合并的细分受众群。 +% 背景: 对于数据修改,ArangoSearch视图遵循“版本化数据存储”的概念。因此,一旦不再有旧数据的用户,就可以删除旧版本的数据。清理和压缩操作的频率由“ consolidationIntervalMsec”控制,并通过“ consolidationPolicy”选择压缩候选对象。 +% consolidationPolicy:巩固应用策略为选择哪段应该合并(默认:{}) +% 背景: 随着每ArangoDB交易进行的插入文档的一个或多个ArangoSearch内部段被创建。同样,对于已删除的文档,包含此类文档的段会将这些文档标记为“已删除”。随着时间的流逝,这种方法会导致创建许多小的和稀疏的段。“合并”操作选择一个或多个段,并将其所有有效文档复制到单个新段中,从而使搜索算法的性能更佳,并且一旦不再使用旧段,就可以释放额外的文件句柄。 +% 子属性: +% type(字符串,可选):根据“合并”操作的类型定义的几种可能的可配置公式选择候选候选者。当前支持的类型是: +% "tier"(默认值):根据段字节大小和活动文档计数(由定制属性指定)进行合并。如果使用此类型,则下面的segments*和minScore属性可用。 +% "bytes_accum":当并且仅 {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes 当即所有候选段字节大小的总和小于总段字节大小乘以{threshold}。如果使用此类型,则下面的threshold属性可用。 +% threshold(数字,可选):范围内的值[0.0, 1.0] +% segmentsBytesFloor(数字,可选):定义值(以字节为单位),以将所有较小的段视为与合并选择相等(默认值:2097152) +% segmentsBytesMax(数字,可选):所有合并段的最大允许大小(以字节为单位)(默认值:5368709120) +% segmentsMax(数字,可选):将被评估为合并候选者的最大细分数(默认值:10) +% segmentsMin(数字,可选):将被评估为合并候选者的最小细分数(默认值:1) +% minScore(数字,可选):(默认值:0) +% writebufferIdle:池中缓存的最大写程序(段)数(默认值:64,使用0禁用,不可变) +% writebufferActive:执行事务的并发活动写程序(段)的最大数量。其他编写器(段)等待当前活动的编写器(段)完成(默认值:0,使用0禁用,不可变) +% writebufferSizeMax:在触发写入器(段)刷新之前,每个写入器(段)的最大内存字节大小。0value会关闭所有写入器(缓冲区)的此限制,并且将根据为刷新线程定义的值(ArangoDB服务器启动选项)定期刷新数据。0由于潜在的高内存消耗,应谨慎使用该值(默认值:33554432,使用0禁用,不可变) +% 创建一个具有给定名称和属性的新视图(如果尚不存在)。 +% 返回码 +% 400:如果name或type属性丢失或无效,则 返回HTTP 400错误。 +% 409:如果已经存在一个名为name的视图,则返回HTTP 409错误。 +newViewOfArangoSearch(PoolNameOrSocket, MapData) -> + case MapData of + #{<<"type">> := <<"arangosearch">>} -> + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Post, <<"/_api/view">>, [], BodyStr); + _ -> + {error, param} + end. + +% 返回有关视图的信息 +% GET /_api/view/{view-name} +% 路径参数 +% view-name(必填):视图的名称。 +% 结果是一个对象,简要描述了具有以下属性的视图: +% id:视图的标识符 +% name:视图的名称 +% type:视图的类型为字符串 +% 返回码 +% 404:如果视图名称未知,则返回HTTP 404。 +getViewInfo(PoolNameOrSocket, ViewName) -> + Path = <<"/_api/view/", ViewName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + + +% 读取指定视图的属性 +% GET /_api/view/{view-name}/properties +% 路径参数 +% view-name(必填):视图的名称。 +% 返回一个对象,其中包含由view-name标识的View的定义。 +% 结果是一个具有特定视图完整描述的对象,包括与视图类型相关的属性。 +% 返回码 +% 400:如果缺少视图名称,则返回HTTP 400。 +% 404:如果视图名称未知,则返回HTTP 404。 +getViewProperties(PoolNameOrSocket, ViewName) -> + Path = <<"/_api/view/", ViewName/binary, "/properties">>, + agHttpCli:callAgency(PoolNameOrSocket, ?Get, Path, [], undefined). + + +% 返回所有视图 +% GET /_api/view +% 返回一个对象,该对象包含数据库中所有视图的列表,无论它们的类型如何。它是具有以下属性的对象数组: +% ID +% 名称 +% 类型 +% 返回码 +% 200:视图列表 +getViewList(PoolNameOrSocket) -> + agHttpCli:callAgency(PoolNameOrSocket, ?Get, <<"/_api/view">>, [], undefined). + +% 更改ArangoSearch视图的所有属性 +% +% PUT /_api/view/{view-name}/properties#ArangoSearch +% 路径参数 +% view-name(必填):视图的名称。 +% 具有以下属性的JSON对象是必需的: +% links:期望一个对象,其属性键为要链接的集合的名称,链接属性为属性值。有关 详细信息,请参见 ArangoSearch查看链接属性。 +% cleanupIntervalStep:在删除ArangoSearch数据目录中的未使用文件之间至少等待这么多次提交(默认值:2,以禁用使用:0)。对于合并策略经常合并段的情况(即大量的commit + consolidate),较低的值将导致浪费大量磁盘空间。对于合并策略很少合并段(即,很少的插入/删除)的情况,较高的值将影响性能,而不会带来任何额外的好处。 +% 背景: 每次执行“提交”或“合并”操作时,都会在磁盘上创建View内部数据结构的新状态。一旦不再有任何用户可用,就会释放旧状态/快照。但是,释放状态/快照的文件保留在磁盘上,只能通过“清理”操作将其删除。 +% commitIntervalMsec:在提交View数据存储更改和使文档对查询可见之前,至少要等待这么多毫秒(默认值:1000,禁用使用:0)。对于插入/更新很多的情况,较低的值(直到提交)将导致索引无法解决这些问题,并且内存使用量将继续增长。对于插入/更新次数很少的情况,较高的值将影响性能并浪费每个提交调用的磁盘空间,而没有任何其他好处。 +% 背景: 对于数据检索,ArangoSearch视图遵循“最终一致”的概念,即,最终ArangoDB中的所有数据将通过相应的查询表达式进行匹配。引入了ArangoSearch View“提交”操作的概念,以控制直到相应的查询表达式实际反映出文档添加/删除的时间的上限。一旦“提交”操作完成,在“提交”操作开始之前添加/删除的所有文档将由后续ArangoDB事务中调用的查询反映,正在进行的ArangoDB事务仍将继续返回可重复读取状态。 +% integrationIntervalMsec:在应用'consolidationPolicy'合并View数据存储与可能释放文件系统上的空间之间至少等待这么多毫秒(默认值:10000,禁用使用:0)。对于存在大量数据修改操作的情况,较高的值可能会使数据存储区消耗更多的空间和文件句柄。对于少量数据修改操作的情况,较低的值将影响性能,因为没有可用于合并的细分受众群。 +% 背景: 对于数据修改,ArangoSearch视图遵循“版本化数据存储”的概念。因此,一旦不再有旧数据的用户,就可以删除旧版本的数据。清理和压缩操作的频率由“ consolidationIntervalMsec”控制,并通过“ consolidationPolicy”选择压缩候选对象。 +% consolidationPolicy:巩固应用策略为选择哪段应该合并(默认:{}) +% 背景: 随着每ArangoDB交易进行的插入文档的一个或多个ArangoSearch内部段被创建。同样,对于已删除的文档,包含此类文档的段会将这些文档标记为“已删除”。随着时间的流逝,这种方法会导致创建许多小的和稀疏的段。“合并”操作选择一个或多个段,并将其所有有效文档复制到单个新段中,从而使搜索算法的性能更佳,并且一旦不再使用旧段,就可以释放额外的文件句柄。 +% 子属性: +% type(字符串,可选):根据“合并”操作的类型定义的几种可能的可配置公式选择候选候选者。当前支持的类型是: +% "tier"(默认值):根据段字节大小和活动文档计数(由定制属性指定)进行合并。如果使用此类型,则下面的segments * 和minScore属性可用。 +% "bytes_accum":当并且仅 {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes 当即所有候选段字节大小的总和小于总段字节大小乘以{threshold}。如果使用此类型,则下面的threshold属性可用。 +% threshold(数字,可选):范围内的值[0.0, 1.0] +% segmentsBytesFloor(数字,可选):定义值(以字节为单位),以将所有较小的段视为与合并选择相等(默认值:2097152) +% segmentsBytesMax(数字,可选):所有合并段的最大允许大小(以字节为单位)(默认值:5368709120) +% segmentsMax(数字,可选):将被评估为合并候选者的最大细分数(默认值:10) +% segmentsMin(数字,可选):将被评估为合并候选者的最小细分数(默认值:1) +% minScore(数字,可选):(默认值:0) +% 通过替换它们来更改视图的属性。 +% 成功后,将返回具有以下属性的对象: +% id:视图的标识符 +% name:视图的名称 +% type:视图类型 +% 所有其他ArangoSearch View实施特定的属性 +% 返回码 +% 400:如果缺少视图名称,则返回HTTP 400。 +% 404:如果视图名称未知,则返回HTTP 404。 +changeViewAllProperties(PoolNameOrSocket, ViewName, MapData) -> + Path = <<"/_api/view/", ViewName/binary, "/properties">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], BodyStr). + +% 部分更改ArangoSearch视图的属性 +% PATCH /_api/view/{view-name}/properties#ArangoSearch +% 路径参数 +% view-name(必填):视图的名称。 +% 具有 +% links:期望一个对象,其属性键为要链接的集合的名称,链接属性为属性值。有关 详细信息,请参见 ArangoSearch查看链接属性。 +% cleanupIntervalStep:在删除ArangoSearch数据目录中的未使用文件之间至少等待这么多次提交(默认值:2,以禁用使用:0)。对于合并策略经常合并段的情况(即大量的commit + consolidate),较低的值将导致浪费大量磁盘空间。对于合并策略很少合并段(即,很少的插入/删除)的情况,较高的值将影响性能,而不会带来任何额外的好处。 +% 背景: 每次执行“提交”或“合并”操作时,都会在磁盘上创建View内部数据结构的新状态。一旦不再有任何用户可用,就会释放旧状态/快照。但是,释放状态/快照的文件保留在磁盘上,只能通过“清理”操作将其删除。 +% commitIntervalMsec:在提交View数据存储更改和使文档对查询可见之前,至少要等待这么多毫秒(默认值:1000,禁用使用:0)。对于插入/更新很多的情况,较低的值(直到提交)将导致索引无法解决这些问题,并且内存使用量将继续增长。对于插入/更新次数很少的情况,较高的值将影响性能并浪费每个提交调用的磁盘空间,而没有任何其他好处。 +% 背景: 对于数据检索,ArangoSearch视图遵循“最终一致”的概念,即,最终ArangoDB中的所有数据将通过相应的查询表达式进行匹配。引入了ArangoSearch View“提交”操作的概念,以控制直到相应的查询表达式实际反映出文档添加/删除的时间的上限。一旦“提交”操作完成,在“提交”操作开始之前添加/删除的所有文档将由后续ArangoDB事务中调用的查询反映,正在进行的ArangoDB事务仍将继续返回可重复读取状态。 +% integrationIntervalMsec:在应用'consolidationPolicy'合并View数据存储与可能释放文件系统上的空间之间至少等待这么多毫秒(默认值:10000,禁用使用:0)。对于存在大量数据修改操作的情况,较高的值可能会使数据存储区消耗更多的空间和文件句柄。对于少量数据修改操作的情况,较低的值将影响性能,因为没有可用于合并的细分受众群。 +% 背景: 对于数据修改,ArangoSearch视图遵循“版本化数据存储”的概念。因此,一旦不再有旧数据的用户,就可以删除旧版本的数据。清理和压缩操作的频率由“ consolidationIntervalMsec”控制,并通过“ consolidationPolicy”选择压缩候选对象。 +% consolidationPolicy:巩固应用策略为选择哪段应该合并(默认:{}) +% 背景: 随着每ArangoDB交易进行的插入文档的一个或多个ArangoSearch内部段被创建。同样,对于已删除的文档,包含此类文档的段会将这些文档标记为“已删除”。随着时间的流逝,这种方法会导致创建许多小的和稀疏的段。“合并”操作选择一个或多个段,并将其所有有效文档复制到单个新段中,从而使搜索算法的性能更佳,并且一旦不再使用旧段,就可以释放额外的文件句柄。 +% 子属性: +% type(字符串,可选):根据“合并”操作的类型定义的几种可能的可配置公式选择候选候选者。当前支持的类型是: +% "tier"(默认值):根据段字节大小和活动文档计数(由定制属性指定)进行合并。如果使用此类型,则下面的segments * 和minScore属性可用。 +% "bytes_accum":当并且仅 {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes 当即所有候选段字节大小的总和小于总段字节大小乘以{threshold}。如果使用此类型,则下面的threshold属性可用。 +% threshold(数字,可选):范围内的值[0.0, 1.0] +% segmentsBytesFloor(数字,可选):定义值(以字节为单位),以将所有较小的段视为与合并选择相等(默认值:2097152) +% segmentsBytesMax(数字,可选):所有合并段的最大允许大小(以字节为单位)(默认值:5368709120) +% segmentsMax(数字,可选):将被评估为合并候选者的最大细分数(默认值:10) +% segmentsMin(数字,可选):将被评估为合并候选者的最小细分数(默认值:1) +% minScore(数字,可选):(默认值:0) +% 通过更新指定的属性来更改视图的属性。 +% 成功后,将返回具有以下属性的对象: +% id:视图的标识符 +% name:视图的名称 +% type:视图类型 +% 所有其他ArangoSearch View实施特定的属性 +% 返回码 +% 400:如果缺少视图名称,则返回HTTP 400。 +% 404:如果视图名称未知,则返回HTTP 404。 +changeViewPartProperties(PoolNameOrSocket, ViewName, MapData) -> + Path = <<"/_api/view/", ViewName/binary, "/properties">>, + BodyStr = jiffy:encode(MapData), + agHttpCli:callAgency(PoolNameOrSocket, ?Patch, Path, [], BodyStr). + +% 重命名视图 +% PUT /_api/view/{view-name}/rename +% 路径参数 +% view-name(必填):要重命名的View的名称。 +% 重命名视图。需要具有属性的对象 +% 名称:新名称 +% 它返回具有属性的对象 +% id:视图的标识符。 +% name:视图的新名称。 +% type:视图类型。 +% 注意:此方法在群集中不可用。 +% 返回码 +% 400:如果缺少视图名称,则返回HTTP 400。 +% 404:如果视图名称未知,则返回HTTP 404。 +renameView(PoolNameOrSocket, ViewName, NewViewName) -> + Path = <<"/_api/view/", ViewName/binary, "/rename">>, + NameStr = jiffy:encode(NewViewName), + agHttpCli:callAgency(PoolNameOrSocket, ?Put, Path, [], <<"{\"name\":", NameStr/binary, "}">>). + +% 删除视图 +% DELETE /_api/view/{view-name} +% 路径参数 +% view-name(必填):要放置的视图的名称。 +% 删除由view-name标识的View 。 +% 如果成功删除了View,则返回具有以下属性的对象: +% 错误:假 +% id:放置的视图的标识符 +% 返回码 +% 400:如果缺少视图名称,则返回HTTP 400。 +% 404:如果视图名称未知,则返回HTTP 404。 +delView(PoolNameOrSocket, ViewName) -> + Path = <<"/_api/view/", ViewName/binary>>, + agHttpCli:callAgency(PoolNameOrSocket, ?Delete, Path, [], undefined). diff --git a/src/httpCli/agHttpCli.erl b/src/httpCli/agHttpCli.erl index 777dcbb..064cf70 100644 --- a/src/httpCli/agHttpCli.erl +++ b/src/httpCli/agHttpCli.erl @@ -14,7 +14,7 @@ , castAgency/6 , castAgency/7 , castAgency/8 - , receiveResponse/1 + , receiveResponse/2 %% 连接池API , startPool/2 @@ -40,8 +40,8 @@ callAgency(PoolNameOrSocket, Method, Path, Headers, Body, IsSystem) -> -spec callAgency(poolNameOrSocket(), method(), path(), headers(), body(), boolean(), timeout()) -> term() | {error, atom()}. callAgency(PoolNameOrSocket, Method, Path, Headers, Body, IsSystem, Timeout) -> case castAgency(PoolNameOrSocket, Method, Path, Headers, Body, self(), IsSystem, Timeout) of - {ok, RequestId} -> - receiveResponse(RequestId); + {ok, RequestId, MonitorRef} -> + receiveResponse(RequestId, MonitorRef); {error, _Reason} = Err -> Err; Ret -> @@ -76,9 +76,10 @@ castAgency(PoolNameOrSocket, Method, Path, Headers, Body, Pid, IsSystem, Timeout undefined -> {error, undefined_server}; AgencyName -> - RequestId = {AgencyName, make_ref()}, + MonitorRef = erlang:monitor(process, AgencyName), + RequestId = {AgencyName, MonitorRef}, catch AgencyName ! #miRequest{method = Method, path = Path, headers = Headers, body = Body, requestId = RequestId, fromPid = Pid, overTime = OverTime, isSystem = IsSystem}, - {ok, RequestId} + {ok, RequestId, MonitorRef} end; _ -> case getCurDbInfo(PoolNameOrSocket) of @@ -124,11 +125,14 @@ castAgency(PoolNameOrSocket, Method, Path, Headers, Body, Pid, IsSystem, Timeout end end. --spec receiveResponse(requestId()) -> term() | {error, term()}. -receiveResponse(RequestId) -> +-spec receiveResponse(requestId(), reference()) -> term() | {error, term()}. +receiveResponse(RequestId, MonitorRef) -> receive #miAgHttpCliRet{requestId = RequestId, reply = Reply} -> - Reply + erlang:demonitor(MonitorRef), + Reply; + {'DOWN', MonitorRef, process, _Pid, Reason} -> + {error, {agencyDown, Reason}} end. -spec receiveTcpData(recvState() | undefined, socket(), reference() | undefined, binary:cp(), binary:cp(), boolean()) -> requestRet() | {error, term()}. diff --git a/src/httpCli/agHttpProtocol.erl b/src/httpCli/agHttpProtocol.erl index 5616a50..201972b 100644 --- a/src/httpCli/agHttpProtocol.erl +++ b/src/httpCli/agHttpProtocol.erl @@ -59,7 +59,7 @@ response(undefined, Rn, RnRn, Data, IsHeadMethod) -> {0, Headers, Rest} -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = 0, body = Rest}}; {chunked, Headers, Body} -> - case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode >= 100 andalso StatusCode < 200) of + case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode < 200 andalso StatusCode >= 100) of true -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = 0, body = Rest}}; _ -> @@ -75,7 +75,7 @@ response(undefined, Rn, RnRn, Data, IsHeadMethod) -> ?WARN(agTcpAgencyIns, "11 contentLength get to long data why? more: ~p ~n", [BodySize - ContentLength]), {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = ContentLength, body = Body}}; true -> - case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode >= 100 andalso StatusCode < 200) of + case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode < 200 andalso StatusCode >= 100) of true -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = ContentLength, body = Body}}; _ -> @@ -126,7 +126,7 @@ response(#recvState{stage = header, body = OldBody}, Rn, RnRn, Data, IsHeadMetho {0, Headers, Body} -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = 0, body = Body}}; {chunked, Headers, Rest} -> - case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode >= 100 andalso StatusCode < 200) of + case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode < 200 andalso StatusCode >= 100) of true -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = 0, body = Rest}}; _ -> @@ -142,7 +142,7 @@ response(#recvState{stage = header, body = OldBody}, Rn, RnRn, Data, IsHeadMetho ?WARN(agTcpAgencyIns, "33 contentLength get to long data why? more: ~p ~n", [BodySize - ContentLength]), {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = ContentLength, body = Body}}; true -> - case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode >= 100 andalso StatusCode < 200) of + case IsHeadMethod orelse StatusCode == 204 orelse StatusCode == 304 orelse (StatusCode < 200 andalso StatusCode >= 100) of true -> {done, #recvState{stage = done, statusCode = StatusCode, headers = Headers, contentLength = ContentLength, body = Body}}; _ ->