python使用Neo4j图数据库——py2neo详解（2）

0 前言

python使用Neo4j图数据库——py2neo详解（1）

1 py2neo.database-Graph Databases

py2neo.database包包含与Neo4j服务器交互所需的类和方法。为方便起见，这些类中的许多类也通过top-level包公开py2neo。

提供的最有用的类是Graph，表示一个Neo4j图形数据库实例并提供对大部分最常用py2neo API的访问的类。

要对本地数据库运行query很简单：

>>> from py2neo import Graph
>>> graph = Graph(password="password")
>>> graph.run("UNWIND range(1, 3) AS n RETURN n, n * n as n_sq").to_table()
   n | n_sq
-----|------
   1 |    1
   2 |    4
   3 |    9

2 GraphService

class py2neo.database.GraphService
通过Bolt或HTTP进行整个Neo4j图形数据库安装的访问器。在py2neo对象层次结构中，GraphService包含Graph大多数活动。
在早期版本中，这个类是Database。
可以将显式URI传递给构造函数：

>>> from py2neo import GraphService
>>> gs = GraphService("bolt://camelot.example.com:7687")

或者，使用默认值bolt://localhost:7687：

>>> default_gs = GraphService()
>>> default_gs
<GraphService uri='bolt://localhost:7687'>

属性：
-config：返回用于配置Neo4j的配置参数的字典。

• default_graph：此图数据库服务公开的默认图。返回类型：Graph。
• kernel_version：返回Neo4j的版本。
• product：返回产品名称。
• system_graph：此图数据库服务公开的图数据库。返回类型：SystemGraph。
• uri：此GraphService连接到的URI 。
  类方法：
• forget_all()：忘记所有缓存的GraphService详细信息。

3 Graph

class py2neo.database.Graph（uri，name= None，** settings）
这个图形类表示的Neo4j图形数据库内的图数据的存储空间。使用URI和（或）单个设置提供连接详细信息。
该name参数允许按名称图形数据库的选择。当使用Neo4j 4.0及更高版本时，它可以是系统目录中定义的任何名称，可以通过Cypher 命令SHOW DATABASES获得其完整列表。此处为None将选择服务器上定义的默认数据库。对于Neo4j的早期版本，名称必须设置为None。

from py2neo import Graph
sales = Graph("bolt+s://g.example.com:7687", name="sales")
sales.run("MATCH (c:Customer) RETURN c.name")
 c.name
---------------
 John Smith
 Amy Pond
 Rory Williams

在所有4.x +产品版本中都可用的系统图也可以通过SystemGraph该类进行访问。

from py2neo import SystemGraph
sg = SystemGraph("bolt+s://g.example.com:7687")
sg.call("dbms.security.listUsers")
 username | roles | flags
----------|-------|-------
 neo4j    |  null | []

支持的URI方案是：

• bolt -Bolt（不安全）
• bolt+s -Bolt（通过完整的证书检查进行保护）
• bolt+ssc -Bolt安全，无证书检查）
• http -HTTP（不安全）
• https -HTTP（通过完整的证书检查进行保护）
• http+s -HTTP（通过完整的证书检查进行保护）
• http+ssc -HTTP（受保护，没有证书检查）

支持的完整设置包括：

keyword	description	type	default
scheme	使用特定的URI方案	str	‘bolt’
secure	使用安全连接（TLS）	bool	False
verify	验证服务器证书（如果安全）	bool	True
host	数据库服务器主机名	str	‘localhost’
port	数据库服务器端口	整型	7687
address	用冒号分隔的主机和端口字符串	str	‘localhost:7687’
user	用户身份验证	str	‘neo4j’
password	用于认证的密码	str	‘password’
auth	2位元组（用户名和密码）	元组	(‘neo4j’, ‘password’)
user_agent	用户代理发送所有连接	str	（取决于URI方案）
max_connections	允许的最大同时连接数	整型	40

每个设置都可以作为关键字参数或URI的一部分提供。因此，以下三个示例都是等效的：

>>> from py2neo import Graph
>>> graph_1 = Graph()
>>> graph_2 = Graph(host="localhost")
>>> graph_3 = Graph("bolt://localhost:7687")

一旦获得，Graph实例将提供对py2neo内大多数可用功能的直接或间接访问。

请注意，py2neo不支持使用Neo4j因果群集进行路由。要使用此功能，请使用官方的Python Neo4j驱动程序。
常用方法：

• auto（readonly= False，after= None，metedata= None，timeout= None）:开始一个新的自动提交GraphTransaction。
• begin（autocommit= False，readonly= False，after= None，metedata= None，timeout= None）：开始一个新的GraphTransaction。
• call（procedure，* args）：通过名称调用过程。
  例如：

from py2neo import Graph
g = Graph()
g.call("dbms.components")
 name         | versions  | edition
--------------|-----------|-----------
 Neo4j Kernel | ['4.0.2'] | community

• create（subgraph）：在GraphTransaction中运行GraphTransaction.create()操作。

• delete（subgraph）：在GraphTransaction中运行操作GraphTransaction.delete()。若要仅删除关系，请使用separate()方法。
  注意，只有通过graph和identity 属性绑定到相应数据库实体的实体才会触发删除。

• delete_all（）：从这个Graph删除所有节点和关系。
  警告 此方法将从图表中永久删除所有节点和关系，并且无法撤消。

• evaluate（cypher，parameters= None，** kwparameters）：在 GraphTransaction中 运行操作GraphTransaction.evaluate()。

  • Parameters:
    • cypher – cypher声明
    • parameters:– 参数字典
  • return:返回的第一个记录的第一个值或 None。

• exists（subgraph）：在 GraphTransaction中 运行操作 GraphTransaction.exists()。

• match（node= None，r_type = None，limit= None）：匹配并返回具有特定条件的所有关系。
  例如，查找所有Alice的朋友：

  • parameters:
    • node –起始和结束节点的序列或集合（None表示任何节点）；集合意味着在任何方向上都匹配
    • r_type –要匹配的关系类型（None表示任何类型）
    • limit –匹配的最大关系数（None意味着无限）

for rel in graph.match((alice, ), r_type="FRIEND"):
    print(rel.end_node["name"])

• match_one（node= None，r_type = None）：匹配并返回具有特定条件的一种关系。
  • parameters：
    • node –起始和结束节点的序列或集合（None表示任何节点）；集合意味着在任何方向上都匹配
    • r_type –要匹配的关系类型（None表示任何类型）
• merge（subgraph，label= None，* property_keys）：在GraphTransaction中运行操作GraphTransaction.merge()。
  下面的示例代码显示了两个新节点之间新关系的简单合并：

from py2neo import Graph, Node, Relationship
g = Graph()
a = Node("Person", name="Alice", age=33)
b = Node("Person", name="Bob", age=44)
KNOWS = Relationship.type("KNOWS")
g.merge(KNOWS(a, b), "Person", "name")

接下来，我们创建两个原始节点都连接到的第三个节点（不同类型）：

c = Node("Company", name="ACME")
c.__primarylabel__ = "Company"
c.__primarykey__ = "name"
WORKS_FOR = Relationship.type("WORKS_FOR")
g.merge(WORKS_FOR(a, c) | WORKS_FOR(b, c))

请注意，这与Cypher MERGE不同。

• play(work，args = None，kwargs = None，after = None，metas = None，timeout = None)：调用代表GraphTransaction工作单元的函数。
  该函数必须始终接受一个GraphTransaction 对象作为其第一个参数。可以通过此方法的args和kwargs参数传递其他参数。
  如果函数具有readonly属性，并且将其设置为真实值，则将在可能的情况下在只读环境中执行。
  如果函数具有timeout属性，并且没有timeout参数传递给此方法调用，则将使用函数属性的值代替设置超时。

  • parameters：
    • work –包含工作单元的功能
    • args –传递给函数的其他位置参数的序列
    • kwargs –传递给函数的其他关键字参数的映射
    • after – 标记交易历史记录中点Bookmark的Bookmark对象，之后应执行此工作单元
    • metas–附加到此事务的用户元数据
    • timeout–事务执行超时

• pull(subgraph)：从数据库中提取到一个或多个实体。

  • subgraph –要提取的节点和关系的集合

• push(subgraph)：将数据从一个或多个实体推送到数据库中对等实体。
  -subgraph –要推送的节点和关系的集合

• 属性nodes：这个图获得一个NodeMatcher。
  这可用于查找符合给定条件的节点：

graph = Graph()
graph.nodes[1234]
(_1234:Person {name: 'Alice'})
graph.nodes.get(1234)
(_1234:Person {name: 'Alice'})
graph.nodes.match("Person", name="Alice").first()
(_1234:Person {name: 'Alice'})

使用此属性也可以有效地计算节点数：

len(graph.nodes)
55691
len(graph.nodes.match("Person", age=33))
12

• 属性relationships：这个图获取一个RelationshipMatcher。
  这可用于查找与给定条件匹配的关系，并有效地计算关系。
• run（cypher，parameters= None，** kw parameters）：在GraphTransaction中 运行操作GraphTransaction.run()。
  • parameters：
    • cypher – cypher声明
    • parameters – 参数字典
    • kwparameters –额外的关键字参数
• schema=None：此Graph的Schema。
• separate(subgraph)：在GraphTransaction中运行操作GraphTransaction.separate()。
  注意，只有通过graph和identity 属性绑定到相应数据库关系才会触发删除。
• service=None：这个Graph所属的GraphService。

类py2neo.database.Schema(graph)
Graph实例的schema。
方法：

• create_index（label，* property_keys）：为标签和属性键组合创建模式索引。
• create_uniqueness_constraint（label，property_key）：为给定标签和属性键创建节点唯一性约束。
  虽然索引支持使用组合键，但唯一约束只能与单个属性键绑定。
• drop_index（label，* property_keys）：删除给定属性键的标签索引。
• drop_uniqueness_constraint（label，property_key）：删除给定标签和属性键的节点唯一性约束。
• get_indexes（label）：获取标签的索引属性键列表。
• get_uniqueness_constraints（label）：获取标签的唯一约束列表。每个约束都是单个属性键的名称。
• 属性node_labels：当前在图中定义的节点标签集。
• 属性relationship_types：图形内当前定义的一组关系类型。

SystemGraph
class py2neo.database.SystemGraph（uri，** settings）
Graph的子类提供对DBMS的系统数据库的访问。仅在Neo4j 4.0及更高版本中可用。

4 Transactions

class py2neo.database.GraphTransaction（autocommit = False）
一个或多个图操作的逻辑上下文。

• commit（）：提交transaction。
• create（subgraph）：创建与本地子图中的节点和关系相对应的数据库节点和关系。子图中的任何已经绑定到数据库的实体将保持不变，那些没有绑定的将在数据库中新建。
  例如：

>>> from py2neo import Graph, Node, Relationship
>>> g = Graph()
>>> tx = g.begin()
>>> a = Node("Person", name="Alice")
>>> tx.create(a)
>>> b = Node("Person", name="Bob")
>>> ab = Relationship(a, "KNOWS", b)
>>> tx.create(ab)
>>> tx.commit()
>>> g.exists(ab)
True

• delete（subgraph）：删除与本地子图中的远程节点和关系相对应的远程节点和关系。若要仅删除关系，请使用separate()方法。
• evaluate（cypher，parameters= None，** kwparameters）：执行单个Cypher语句，并从第一条记录的第一列返回值。
• exists（subgraph）：确定图中是否存在一个或多个实体。请注意，如果子图中的任何节点或关系都未绑定到远程副本，则此方法将返回False。
• finished（）：指示此事务是否已完成或仍处于打开状态。
• merge（subgraph, primary_label=None, primary_key=None）：在远程数据库中创建或更新本地子图的节点和关系。请注意，此操作的功能与Cypher MERGE子句并不严格相同，尽管存在一些重叠。
  本地子图中的每个节点和关系都独立合并，其中节点首先合并，然后关系合并。
  对于每个节点，通过根据单个标签和属性值将该节点与潜在的远程等效对象进行比较来执行合并。如果找不到远程匹配项，则创建一个新节点；如果找到匹配项，则更新远程节点的标签和属性。用于比较的标签和属性由primary_label和primary_key参数确定，但对于单个节点，可以由节点本身上的__primarylabel__和 __primarykey__属性覆盖。
  对于每个关系，通过在匹配起始节点和结束节点以及关系类型的基础上，将该关系与潜在的远程等效项进行比较，来执行合并。如果找不到远程匹配项，则创建一个新的关系；如果找到匹配项，则更新远程关系的属性。
  • parameters：
    • subgraph -一个Node，Relationship或其他 Subgraph对象
    • primary_label –匹配任何现有节点的标签
    • primary_key –匹配任何现有节点的属性键
• pull(subgraph)：从远程数据库对等实体更新本地实体。
  对于本地Subgraph和远程中都存在的任何节点和关系 Graph，将属性和节点标签拉到本地副本中。此操作不会创建或删除任何实体。
• push（subgraph）：从本地副本更新远程实体。
  对于本地Subgraph和远程中都存在的任何节点和关系 Graph，将属性和节点标签推送到远程副本中。此操作不会创建或删除任何实体。
• rollback（）：回滚当前事务transaction，撤消先前执行的所有操作。
• run（cypher, parameters=None, **kwparameters）：将Cypher语句发送到服务器以执行，并返回aCursor来导航其结果。
• separate（subgraph）：删除与本地子图中的远程关系相对应的远程关系。这使所有节点保持不变。

5 Cypher Results

class py2neo.database.Cursor（result, hydrant=None, entities=None）
cursor记录record流。
可以将游标视为基础数据流上的窗口。py2neo中的所有游标都是“仅向前”的，这意味着导航在第一个记录之前开始，并且可能仅在向前方向上进行。
应用程序代码通常不需要直接实例化游标，因为任何Cypher执行方法都将返回该游标。但是，创建游标仅需要一个DataSource对象，该对象包含如何访问游标导航的源数据的逻辑。
许多简单的游标用例仅需要forward()方法和current属性。要浏览所有可用记录，可以使用while循环：

while cursor.forward():
    print(cursor.current["name"])

如果只关注第一个记录，则类似的if结构将完成此工作：

if cursor.forward():
    print(cursor.current["name"])

要将正向和电流合并为一个步骤，请使用内置的python方法：next函数：

print(next(cursor)["name"])

游标也是可迭代的，因此可以循环使用：

for record in cursor:
    print(record["name"])

对于期望在单个记录中仅返回单个值的查询，请使用evaluate()方法。这将从下一条记录返回第一个值，如果字段和记录均不存在，则返回None：

print(cursor.evaluate())

• close（）：关闭此光标并释放所有关联的资源。
• 属性current：返回当前记录，或者None尚未选择任何记录。
• data（）：使用并提取整个结果作为词典列表。

>>> from py2neo import Graph
>>> graph = Graph()
>>> graph.run("MATCH (a:Person) RETURN a.name, a.born LIMIT 4").data()
[{'a.born': 1964, 'a.name': 'Keanu Reeves'},
 {'a.born': 1967, 'a.name': 'Carrie-Anne Moss'},
 {'a.born': 1961, 'a.name': 'Laurence Fishburne'},
 {'a.born': 1960, 'a.name': 'Hugo Weaving'}]

• evaluate（field=0）：从下一条记录返回第一个字段的值（如果明确指定，则返回另一个字段的值）。
  此方法尝试将光标向前移动一个步骤，如果成功，则从新的当前记录中选择并返回一个单独的值。默认情况下，该值将从该记录中的第一个值获取，但是可以用field参数覆盖，该参数可以表示位置索引或文本键。

如果光标不能向前移动，或者记录中没有任何值，则将返回None。

当已知Cypher查询仅返回单个值时，此方法特别有用。
例

from py2neo import Graph
g = Graph()
g.run("MATCH (a) WHERE a.email=$x RETURN a.name", x="bob@acme.com").evaluate()
'Bob Robertson'

• forward（amount=1）：尝试将光标向前移动一个位置（如果明确指定，则移动另一个位置）。光标将移动位置最多但不超过指定的数量。如果没有足够的移动余地，则将仅消耗剩余部分。返回移动的总金额。
• keys（）：返回流中记录的字段名称。
• plan（）：返回返回此结果的计划（如果有）。
• preview（limit= 1）：构建一个Table包含即将到来的记录的预览的，包括不超过给定的limit。
• stats（）：返回查询统计信息。
  它包含数据库内核为查询执行的活动的详细信息，例如创建或删除的实体数。具体来说，这将返回一个CypherStats对象。

from py2neo import Graph
g = Graph()
g.run("CREATE (a:Person) SET a.name = 'Alice'").stats()
constraints_added: 0
constraints_removed: 0
contained_updates: True
indexes_added: 0
indexes_removed: 0
labels_added: 1
labels_removed: 0
nodes_created: 1
nodes_deleted: 0
properties_set: 1
relationships_created: 0
relationships_deleted: 0

• summary（）:返回结果摘要。
• to_data_frame（index=None, columns=None, dtype=None）：将整个结果提取为 pandas.DataFrame。

>>> from py2neo import Graph
>>> graph = Graph()
>>> graph.run("MATCH (a:Person) RETURN a.name, a.born LIMIT 4").to_data_frame()
   a.born              a.name
0    1964        Keanu Reeves
1    1967    Carrie-Anne Moss
2    1961  Laurence Fishburne
3    1960        Hugo Weaving

注意 此方法需要安装pandas。

• to_matrix（mutable=False）：提取整个结果作为 sympy.Matrix。
  注意 此方法需要安装sympy。
• to_ndarray（dtype = None，order = ‘K’）：提取整个结果作为 numpy.ndarray。
  注意 此方法需要安装numpy。
• to_series（field=0, index=None, dtype=None）：提取整个结果的一个字段作为 pandas.Series。
  注意 此方法需要安装pandas。
• to_subgraph（）：Subgraph 包含并提取所有结果，作为其中包含所有图结构的并集。
• to_table（）：提取整个结果作为一个Table 对象。

class py2neo.database.CypherStats（**stats）
从Cypher查询执行中提取的一组统计信息的容器。
每个值都可以作为属性或通过字符串索引进行访问。此类实现Mapping为允许将其用作字典。

• constraints_added= 0：添加的约束数量。
• constraints_removed=0： :除去约束的数量。
• contained_updates=False：布尔标志，指示查询是否包含更新。
• indexes_added= 0：添加的索引数。
  :- indexes_removed= 0：删除的索引数。
• keys（）：可用统计信息的键或属性名称的完整列表。
• labels_added= 0：添加的节点标签数。
• labels_removed= 0：删除的节点标签数。
• nodes_created= 0：创建的节点数。
• nodes_deleted= 0：删除的节点数。
  -properties_set= 0：设置的属性值数量。
  -relationships_created= 0：创建的关系数。
• relationships_deleted= 0：关系数已删除。

6 Errors & Warnings

class py2neo.database.GraphError（* args，** kwargs）
class py2neo.database.ClientError（* args，** kwargs）
客户发送了错误的请求-更改请求可能会产生成功的结果。
class py2neo.database.DatabaseError（* args，** kwargs）
数据库无法处理请求。
class py2neo.database.TransientError（* args，** kwargs）
数据库现在无法处理请求，稍后重试可能会产生成功的结果。
class py2neo.database.GraphTransactionError（* args，** kwargs）
当尝试针对GraphTransaction 不再可用的或交易无效时引发。