add ES function (#1886)

* add ES function * update * update * update * update * update * update * update * update * update * update * update * Update 17.ES-function.md * Update docs-2.0/3.ngql-guide/6.functions-and-expressions/17.ES-function.md Co-authored-by: abby.huang <78209557+abby-cyber@users.noreply.github.com> * Update docs-2.0/4.deployment-and-installation/6.deploy-text-based-index/1.text-based-index-restrictions.md Co-authored-by: abby.huang <78209557+abby-cyber@users.noreply.github.com> * Update docs-2.0/4.deployment-and-installation/6.deploy-text-based-index/1.text-based-index-restrictions.md Co-authored-by: abby.huang <78209557+abby-cyber@users.noreply.github.com> * Update mkdocs.yml Co-authored-by: abby.huang <78209557+abby-cyber@users.noreply.github.com>
vesoft-inc · Jun 30, 2022 · 003835d · 003835d
1 parent 921ecf1
commit 003835d
Show file tree

Hide file tree

Showing 4 changed files with 113 additions and 1 deletion.
diff --git a/....0/3.ngql-guide/15.full-text-index-statements/1.search-with-text-based-index.md b/....0/3.ngql-guide/15.full-text-index-statements/1.search-with-text-based-index.md
@@ -175,3 +175,4 @@ nebula> LOOKUP ON player WHERE FUZZY(player.name, "Tim Dunncan", AUTO, OR) YIELD
 //删除全文索引。
 nebula> DROP FULLTEXT INDEX nebula_index_1;
 ```
+
diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/17.ES-function.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/17.ES-function.md
@@ -0,0 +1,106 @@
+# Elasticsearch 查询函数
+
+Elasticsearch 查询函数可以让 Nebula Graph 向 Elasticsearch 发送 GET 请求读取数据，并将返回的 JSON 转换为 Nebula Graph 内的 map 格式，以便用于同一个复合图查询语句中。
+
+关于 Elasticsearch 语法，请参见 [Elasticsearch 官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html)。
+
+!!! enterpriseonly
+
+    仅企业版支持本功能。
+
+## 注意事项
+
+- 不能使用已经部署了全文索引的 Elasticsearch 服务，需要使用独立部署的 Elasticsearch 服务，并且用户需要自行向 Elasticsearch 中写入数据，Nebula Graph 不会向该 Elasticsearch 写入数据。部署 Elasticsearch 集群请参见 [Kubernetes 安装 Elasticsearch](https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-deploy-elasticsearch.html) 或[单机安装 Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.15/targz.html)。
+
+- 使用前需要 SIGN IN 服务，例如`SIGN IN TEXT SERVICE (127.0.0.1:9200, HTTP)`，不再使用时可以 SIGN OUT 服务。具体语法请参见[登录文本搜索客户端](../../4.deployment-and-installation/6.deploy-text-based-index/2.deploy-es.md#_3)。
+
+- 只支持 GET 请求。请用 Elasticsearch 客户端执行 POST、PUT、DELETE 请求。
+
+- 没有超时时间，Nebula Graph 会一直等待 Elasticsearch 返回结果。
+
+- 不支持函数后直接跟操作符，例如`RETURN calles("/test/player/1")["_source"]`。
+
+- 兼容 Elasticsearch 7 及以上版本，更低版本未测试。
+
+## openCypher 兼容性
+
+本文操作仅适用于 openCypher 方式。
+
+## 语法
+
+可以通过 calles() 直接执行 Elasticsearch 语句，也可以通过 callesfile() 执行指定文件内的 Elasticsearch 语句。
+
+```ngql
+calles("<es_query>");
+callesfile("<es_query_file_path>");
+```
+
+- 返回类型：map。Elasticsearch 返回 JSON 格式字符串，Nebula Graph 转换成 map 格式。
+
+## 示例
+
+```ngql
+nebula> RETURN calles("/test/player/1") AS a;
++---------------------------------------------------------------------------------------------------------------------------------------------+
+| a                                                                                                                                           |
++---------------------------------------------------------------------------------------------------------------------------------------------+
+| {_id: "1", _index: "test", _primary_term: 1, _seq_no: 0, _source: {age: 43, name: "Tim Duncan"}, _type: "player", _version: 1, found: true} |
++---------------------------------------------------------------------------------------------------------------------------------------------+
+
+nebula> WITH calles("/test/player/1") AS a RETURN a;
++---------------------------------------------------------------------------------------------------------------------------------------------+
+| a                                                                                                                                           |
++---------------------------------------------------------------------------------------------------------------------------------------------+
+| {_id: "1", _index: "test", _primary_term: 1, _seq_no: 0, _source: {age: 43, name: "Tim Duncan"}, _type: "player", _version: 1, found: true} |
++---------------------------------------------------------------------------------------------------------------------------------------------+
+
+nebula> WITH calles("/test/player/1") AS a \
+        MATCH (b:player) WHERE b.player.age == a["_source"]["age"] \
+        RETURN b;
++---------------------------------------------------+
+| b                                                 |
++---------------------------------------------------+
+| ("player141" :player{age: 43, name: "Ray Allen"}) |
++---------------------------------------------------+
+
+//对于不存在的数据，会返回 found 字段为 false。
+nebula> WITH calles("/test/player/123") AS a RETURN a;
++-------------------------------------------------------------+
+| a                                                           |
++-------------------------------------------------------------+
+| {_id: "123", _index: "test", _type: "player", found: false} |
++-------------------------------------------------------------+
+
+//对于不存在的文件，会返回报错 read Elaticsearch file fail。
+nebula> RETURN callesfile('/home/xxx/es_query_test.txt');
++---------------------------------------------+
+| callESFile( "/home/xxx/es_query_test.txt" ) |
++---------------------------------------------+
+| {error: "read Elaticsearch file fail."}     |
++---------------------------------------------+
+
+nebula> RETURN callesfile('/home/xxx/es_query.txt');
++--------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| callESFile( "/home/xxx/es_query.txt"    )                                                                                                                    |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| {_shards: {failed: 0, skipped: 0, successful: 1, total: 1}, hits: {hits: [{_id: "2", _index: "test", _score: 1.0, _source: {age: 36, name: "Tony Parker"}... |
++--------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+nebula> WITH callesfile('/home/xxx/es_query.txt') AS s RETURN [n in s["hits"]["hits"]|n.`_source`.name];
++--------------------------------------------------------------------------------------------------------------------------------------+
+| [n IN s["hits"]["hits"] | n._source.name]                                                                                            |
++--------------------------------------------------------------------------------------------------------------------------------------+
+| ["LeBron James", "Danny Green", "Kevin Durant", "Stephen Curry", "Rudy Gay", "Ray Allen", "Tim Duncan", "Tony Parker", "Chris Paul"] |
++--------------------------------------------------------------------------------------------------------------------------------------+
+
+nebula> WITH callesfile('/home/xxx/es_query.txt') AS s \
+        MATCH p= (a:player)-[:serve]->() \
+        WHERE id(a) in [n in s["hits"]["hits"]|n.`_source`.name] RETURN p;
++---------------------------------------------------------------------------------------------------------------------------------------------------+
+| p                                                                                                                                                 |
++---------------------------------------------------------------------------------------------------------------------------------------------------+
+| <("LeBron James" :player{age: 34, name: "LeBron James"})-[:serve@1 {end_year: 2018, start_year: 2014}]->("Cavaliers" :team{name: "Cavaliers"})>   |
+| <("LeBron James" :player{age: 34, name: "LeBron James"})-[:serve@0 {end_year: 2010, start_year: 2003}]->("Cavaliers" :team{name: "Cavaliers"})>   |
+...
+```
diff --git a/...t-and-installation/6.deploy-text-based-index/1.text-based-index-restrictions.md b/...t-and-installation/6.deploy-text-based-index/1.text-based-index-restrictions.md
@@ -22,7 +22,9 @@
 
 - 全文索引不支持搜索属性值为`NULL`的属性。
 
-- 不支持修改 Elastic Search 中的索引，只能删除重建。
+- 写入数据时，Elasticsearch 会自动创建相应的索引。在 Nebula Graph 中创建全文索引，但是未写入数据，查询时会报错`text search not found`。
+
+- 不支持修改 Elasticsearch 中的索引，只能删除重建。
 
 - 不支持管道符。
 
@@ -37,3 +39,5 @@
 - 从写入 Nebula Graph，到写入 listener，再到写入 Elasticsearch 并创建索引可能需要一段时间。如果访问全文索引时返回未找到索引，可等待索引生效（但是，该等待时间未知，也无返回码检查）。
 
 - 使用 K8s 方式部署的 Nebula Graph 集群不支持全文索引。
+
+- 不能与 [calles()](../../3.ngql-guide/6.functions-and-expressions/17.ES-function.md) 函数同时使用。
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -295,6 +295,7 @@ nav:
           - 条件表达式函数: 3.ngql-guide/6.functions-and-expressions/5.conditional-expressions.md
           - 谓词函数: 3.ngql-guide/6.functions-and-expressions/8.predicate.md
           - geo 函数: 3.ngql-guide/6.functions-and-expressions/14.geo.md
+          - Elasticsearch 查询函数: 3.ngql-guide/6.functions-and-expressions/17.ES-function.md
           - 自定义函数: 3.ngql-guide/6.functions-and-expressions/9.user-defined-functions.md
 
       - 通用查询语句: