.. _OpenCypher:

########################
OpenCypher Documentation
########################


execute_query
======================
用于执行OpenCypher查询。

**函数声明**

.. code:: python

    execute_query(self, cypher: str, timeout: int = None, def_limit: int = None) -> BoltStatementResult

**参数说明**

=====================    =====================    =============    =================================================================
**Parameter**            **Optional**             **Type**         **DESC**
cypher                   Y                        str              查询语句，**不能为空**
timeout                  N                        int              超时时间，**必须大于0, 或者为None。**
def_limit                N                        int              返回结果数限制，**小于0或者为None表示不进行限制.**
=====================    =====================    =============    =================================================================

**响应参数**

=====================    =========================================    =================================
**Parameter**            **Type**                                     **DESC**
-                        :ref:`BoltStatementResult`                   OpenCypher执行结果
=====================    =========================================    =================================

**异常**

=====================================    =============================================================================
**Type**                                 **DESC**
ParamException                           参数格式不正确，当cypher为空、timeout小于等于0时将抛出异常。
DatabaseException                        数据库内部异常，在cypher语法错误时将抛出异常。
=====================================    =============================================================================

**示例**

.. code:: python

    # 匹配id为19947498的点并打印
    result = graph.execute_query("MATCH (n) WHERE id(n)=19947498 RETURN n")
    for i in result:
      print(i)


execute_cypher
======================
用于执行OpenCypher查询，与`execute_query`相比参数设置更加自由。

**函数声明**

.. code:: python

    def execute_cypher(self, cypher: str, parameters: Union[Dict[str, Any], None]) -> BoltStatementResult

**参数说明**

=========================    =====================    =============    =================================
**Parameter**                **Optional**             **Type**         **DESC**
cypher                       Y                        str              查询语句，**不能为空。**
parameters                   N                        dict             查询可用的参数
=========================    =====================    =============    =================================

**响应参数**

=====================    =========================================    =================================
**Parameter**            **Type**                                     **DESC**
-                        :ref:`BoltStatementResult`                   OpenCypher执行结果
=====================    =========================================    =================================

**异常**

=====================================    =========================================================
**Type**                                 **DESC**
ParamException                           参数类型不正确，当cypher为空时将抛出异常。
DatabaseException                        数据库内部异常，在cypher语法错误时将抛出异常。
=====================================    =========================================================

.. code:: python

    # 匹配id为19947498的点并打印
    result = graph.execute_cypher("MATCH (n) WHERE id(n)=19947498 RETURN n")
    for i in result:
        print(i)

    # 匹配id为19947498的点并打印
    # parameters中的key对应cypher语句中的占位符
    cypher = "match (n) where n.id=$nId return n"
    parameters = {"nId": "19947498"}
    result = graph.execute_cypher(cypher, parameters)


.. note::
    图库支持库级别的cypher调用

    .. code:: python

        driver = GraphDb.connect(uri, user, password)
        # 打印图库用户
        for i in driver.execute_cypher("SHOW ALL USER"):
            print(i)

get_cypher_metrics
======================
获取正在执行的OpenCypher语句信息。

**函数声明**

.. code:: python

    def get_cypher_metrics(self) -> Dict[int, CypherQuery]

**响应参数**

=====================    =================================================    =============================
**Parameter**            **Type**                                             **DESC**
-                        Dict[int, CypherQuery]                               OpenCypher信息
=====================    =================================================    =============================

**示例**

.. code:: python

    # from graphdbapi.v1.CypherQuery import CypherQuery
    #CypherQuery 参考2.2节
    # 查询正在执行的cypher信息
    records = graph.get_cypher_metrics()

stop_cypher
======================
停止指定taskId的 OpenCypher语句。


**函数声明**

.. code:: python

    def stop_cypher(self, task_id: int) -> None

**参数说明**

=====================    =====================    =============    =====================================================
**Parameter**            **Optional**             **Type**         **DESC**
task_id                  Y                        int              cypher taskId，**不能小于0。**
=====================    =====================    =============    =====================================================

**异常**

=================================    =====================================================
**Type**                             **DESC**
ParamException                       参数格式不正确，当taskId小于0时将抛出异常。
=================================    =====================================================

**示例**

.. code:: python

    graph.stop_cypher(task_id)