zc.relation 2.0

概述

关系目录可用于优化有限、预设维度的N元关系的不传递和传递搜索。

例如，您可以索引简单的双向关系，如员工到主管；主题-谓词-对象风格的RDF三元组；以及更复杂的关系，例如具有上下文和状态的主题-谓词-对象。这些可以以可变定义的传递行为进行搜索。

该目录可用于ZODB或独立使用。它是一个通用、相对无政策的工具。

通常期望它作为更专业化和受限制的工具和API的引擎使用。这样的工具有zc.relationship容器、plone.relations容器和zc.vault。该包中的文档（包括本文件），描述了其他可能的用途。

历史

这是对zc.relationship包仅限于ZODB部分的重构。具体来说，zc.relation目录在很大程度上等同于zc.relationship索引。zc.relationship 2.x线中的索引是zc.relation目录的一个几乎完全向后兼容的包装器。尽管zc.relationship将继续维护，但预期活跃的开发将进入zc.relation。

许多想法来自与Casey Duncan、Tres Seaver、Ken Manheimer等人讨论和代码。

设置关系目录

在本节中，我们将介绍以下概念。

• 关系是具有索引值的对象。

• 您可以向关系目录添加值索引以进行搜索。值可以使用可调用或接口元素识别到目录中。必须将索引值指定为目录中的单个值或集合。

• 关系及其值以令牌的形式存储在目录中：唯一标识符，您可以将其解析回原始值。整数是最有效的令牌，但其他也可以工作得很好。

• 令牌类型决定了所需的BTree模块。

• 您必须定义自己的令牌化和解析令牌的函数。这些函数被注册到目录中，用于关系及其每个值索引。

• 关系用索引（index）索引。

我们将使用一个简单的双向关系作为示例。有关更复杂的RDF风格的主题-谓词-对象设置的简要介绍，可以在文档的后面找到。

            Alice
         __/     \__
    Betty           Chuck
    /   \           /   \
Diane   Edgar   Frank   Galyn
  |
Howie

搜索

在本节中，我们将介绍以下概念。

• 对关系目录的查询是用字典形成的。

• 查询键是要搜索的索引名称，或者在精确关系的特殊情况下，是zc.relation.RELATION常量。

• 查询值是要匹配的结果的标记；或者None，表示值为None的关系（或者如果是多个，则为空集合）。搜索值可以使用zc.relation.catalog.any(args)或zc.relation.catalog.Any(args)来指定多个（非None）结果以匹配给定的键。

• 索引有多种方法可以帮助您处理标记。通常最常用的是tokenizeQuery，尽管还有其他方法可用。

• 要找到与查询匹配的关系，请使用findRelations或findRelationTokens。

• 要找到与查询匹配的值，请使用findValues或findValueTokens。

• 通过使用查询工厂进行传递搜索。zc.relation.queryfactory.TransposingTransitive是一个好的通用案例工厂，允许您在层次结构中向上和向下遍历。查询工厂可以作为参数传递给搜索方法作为queryFactory，或者使用addDefaultQueryFactory安装为默认行为。

• 要找到查询是如何相关的，请使用findRelationChains或findRelationTokenChains。

• 要确定查询是否相关，请使用canFind。

• 循环传递关系通过处理以防止无限循环。它们在findRelationChains和findRelationTokenChains中通过zc.relation.interfaces.ICircularRelationPath标记接口来识别。

• 搜索方法共享以下参数

  • maxDepth，限制搜索的传递深度；

  • filter，允许代码过滤传递路径；

  • targetQuery，允许查询基于端点过滤传递路径；

  • targetFilter，允许代码基于端点过滤传递路径；以及

  • queryFactory，上面提到过。

• 您可以设置搜索索引以加快特定传递搜索。

      ______
     /      \
    /     Zane
   /        |
  /       Alice
 /     __/     \__
/ Betty__         Chuck
\-/  /   \         /   \
   Diane Edgar Frank   Galyn
    |
  Howie

处理更复杂的关系

到目前为止，我们的示例使用了简单的关系，其中索引对象是关系的一端，对象上的索引值是另一端。这个例子让我们看到了 zc.relation 目录功能的基本功能。

然而，如介绍中提到的，目录支持，并且是为了支持更复杂的关系而设计的。本节将简要检查一些其他用例的示例。

在本节中，我们将看到几个上面提到但尚未演示的示例。

• 我们可以使用接口属性（值或可调用对象）来定义值索引。

• 使用接口属性会导致尝试适配关系，如果关系尚未提供接口。

• 在定义值索引时，我们可以使用 multiple 参数来指示索引值是一个集合。

• 在定义值索引时，我们可以使用 name 参数来指定查询中要使用的名称，而不是依赖于接口属性或可调用对象的名字。

• 在实例化目录时，family 参数允许你将关系和值索引的默认 btree family 从 BTrees.family32.IF 改为 BTrees.family64.IF。

Karyn   Lee
     \ /
    Jacob   Iphigenia
         \ /
        Gertrude    Harry
                \  /
             /-------\
         Fred        Eugenia
           Donald   /     \    Charles
                 \ /       \  /
                Betty      Alice

附加功能

本节介绍了辅助功能。我们将学习以下内容。

• 可以在目录中注册监听器。当关系被添加、修改或删除时，以及当目录被清除和复制时（见下文），它们会收到通知。

• clear方法清除目录中的关系。

• copy方法通过复制内部数据结构来创建当前目录的副本，而不是重新索引关系，这可以是一个显著的优化机会。这复制了值索引和搜索索引；并给监听器提供了一个机会来指定在新副本中包含什么，如果有的话。

• 五个相关搜索方法的ignoreSearchIndex参数会导致搜索忽略搜索索引，即使存在合适的索引。

• findRelationTokens()（不带参数）返回目录中所有关系令牌的BTree集合。

• findValueTokens(INDEX_NAME)（其中“INDEX_NAME”应替换为索引名称）返回目录中给定索引名称的所有值令牌的BTree集合。

结论

简介和设置

本文假设您已阅读介绍性的 README.rst 并想通过示例了解更多。在它里面，我们将探索一组更复杂的关系，这些关系展示了与标记一起工作的各个方面。特别是，我们将查看连接，这将给我们一个机会更深入地查看查询工厂和搜索索引，并介绍监听器这一概念。它不会解释 README 已经涉及的基本内容。

假设我们在一个系统中索引安全断言。在这个系统中，用户可能在一个组织中拥有角色。每个组织可能有多个子组织，并且可能有一个父组织。在父组织中拥有角色的用户将在所有传递连接的子关系中拥有相同的角色。

因此，我们有两种关系。一种关系将模拟组织的层次结构。我们将使用组织与其子组织之间的内在关系来实现：这反映了父组织选择并由其子组织组成的事实；子组织不选择其父母。

另一种关系将模拟（多个）用户在（单个）组织中拥有的（单个）角色。这种关系将完全是外在的。

我们可以为每种类型创建两个目录，或者我们可以将它们都放在同一个目录中。最初，我们将采用单一目录的方法来展示我们的示例。因此，这个单一目录将索引一组异质的关系。

让我们使用接口定义这两个关系。我们将包括一个访问器getOrganization，主要为了展示如何处理方法。

>>> import zope.interface
>>> class IOrganization(zope.interface.Interface):
...     title = zope.interface.Attribute('the title')
...     parts = zope.interface.Attribute(
...         'the organizations that make up this one')
...
>>> class IRoles(zope.interface.Interface):
...     def getOrganization():
...         'return the organization in which this relation operates'
...     principal_id = zope.interface.Attribute(
...         'the pricipal id whose roles this relation lists')
...     role_ids = zope.interface.Attribute(
...         'the role ids that the principal explicitly has in the '
...         'organization.  The principal may have other roles via '
...         'roles in parent organizations.')
...

现在我们可以创建一些类。在README示例中，设置有点像玩具。这次我们将更实际一些。我们还将期望在ZODB中操作，包括根和事务。 [14]

以下是我们将如何转储和加载数据：使用一个类似于intid工具的“注册”对象。 [15]

在这个“转储”方法的实现中，我们只是使用缓存来向您展示您可能如何使用它。这可能对于这项工作来说有点过度，甚至可能是一个速度损失，但您可以了解这个想法。

>>> def dump(obj, catalog, cache):
...     reg = cache.get('registry')
...     if reg is None:
...         reg = cache['registry'] = catalog._p_jar.root()['registry']
...     return reg.getId(obj)
...
>>> def load(token, catalog, cache):
...     reg = cache.get('registry')
...     if reg is None:
...         reg = cache['registry'] = catalog._p_jar.root()['registry']
...     return reg.getObject(token)
...

现在我们可以创建一个关系目录来保存这些项目。

>>> import zc.relation.catalog
>>> catalog = root['catalog'] = zc.relation.catalog.Catalog(dump, load)
>>> transaction.commit()

现在我们设置我们的索引。我们将从组织开始，并用它们设置目录。这部分将与README.rst中的示例类似，但将引入更多关于优化和标记的讨论。然后我们将添加关于角色的部分，并探讨查询和基于标记的“连接”。

组织

组织将保存一组组织。实际上，这在ZODB中并不容易，因为这意味着我们需要比较或散列持久性对象，这在机器之间以及时间上并不可靠。为了绕过这个问题，并仍然做一些有趣且真实的事情，我们将使用上面引入的注册标记。这也会给我们机会进一步讨论优化和标记。（如果您想以合理且透明的方式保存一组持久性对象，请尝试使用zc.set包XXX，但尚未完成。）

>>> import BTrees
>>> import persistent
>>> @zope.interface.implementer(IOrganization)
... @total_ordering
... class Organization(persistent.Persistent):
...
...     def __init__(self, title):
...         self.title = title
...         self.parts = BTrees.family32.IF.TreeSet()
...     # the next parts just make the tests prettier
...     def __repr__(self):
...         return '<Organization instance "' + self.title + '">'
...     def __lt__(self, other):
...         # pukes if other doesn't have name
...         return self.title < other.title
...     def __eq__(self, other):
...         return self is other
...     def __hash__(self):
...         return 1  # dummy
...

好的，现在我们知道组织将如何工作。现在我们可以向目录添加一个“部分”索引。这将比我们在README中添加索引时做几件新的事情。

>>> catalog.addValueIndex(IOrganization['parts'], multiple=True,
...                       name="part")

那么，与README示例相比有什么不同呢？

首先，我们使用接口元素来定义要索引的值。它提供了一个接口，对象将被适配，一个默认的索引名称，以及有关是否应直接使用属性或调用的信息。

其次，我们未指定转储或加载操作。它们为空。这意味着索引值已可视为一个标记。如果索引值是一个大型集合，并且使用与索引相同的BTree家族，这可以显著优化重新索引操作——这引出了下一个差异。

第三，我们指定了multiple=True。这意味着给定关系上提供或可适配到IOrganization的值将有一个部分集合。无论实际集合是BTrees集合还是BTree的键，这些都将被视为一个集合。

最后，我们指定了用于查询的名称。我发现，当查询键为单数时，查询更易读，所以我经常将复数改写为单数。

如README中所述，我们可以添加另一个简单的转换传递查询工厂，在‘部分’和None之间切换。

>>> import zc.relation.queryfactory
>>> factory1 = zc.relation.queryfactory.TransposingTransitive(
...     'part', None)
>>> catalog.addDefaultQueryFactory(factory1)

让我们也添加一些搜索索引，用于向上查找……

>>> import zc.relation.searchindex
>>> catalog.addSearchIndex(
...     zc.relation.searchindex.TransposingTransitiveMembership(
...         'part', None))

……以及向下。

>>> catalog.addSearchIndex(
...     zc.relation.searchindex.TransposingTransitiveMembership(
...         None, 'part'))

请注意：向上查找的搜索索引在实际上并不是一个好的主意。该索引是为向下查找设计的[16]。

让我们创建并添加一些组织。

我们将创建一个类似这样的结构[24]

        Ynod Corp Mangement                 Zookd Corp Management
         /      |      \                       /      |      \
  Ynod Devs  Ynod SAs  Ynod Admins  Zookd Admins   Zookd SAs  Zookd Devs
    /      \              \                 /                /         \
Y3L4 Proj  Bet Proj      Ynod Zookd Task Force      Zookd hOgnmd     Zookd Nbd

这里是Python代码。

>>> orgs = root['organizations'] = BTrees.family32.OO.BTree()
>>> for nm, parts in (
...     ('Y3L4 Proj', ()),
...     ('Bet Proj', ()),
...     ('Ynod Zookd Task Force', ()),
...     ('Zookd hOgnmd', ()),
...     ('Zookd Nbd', ()),
...     ('Ynod Devs', ('Y3L4 Proj', 'Bet Proj')),
...     ('Ynod SAs', ()),
...     ('Ynod Admins', ('Ynod Zookd Task Force',)),
...     ('Zookd Admins', ('Ynod Zookd Task Force',)),
...     ('Zookd SAs', ()),
...     ('Zookd Devs', ('Zookd hOgnmd', 'Zookd Nbd')),
...     ('Ynod Corp Management', ('Ynod Devs', 'Ynod SAs', 'Ynod Admins')),
...     ('Zookd Corp Management', ('Zookd Devs', 'Zookd SAs',
...                                'Zookd Admins'))):
...     org = Organization(nm)
...     for part in parts:
...         ignore = org.parts.insert(registry.getId(orgs[part]))
...     orgs[nm] = org
...     catalog.index(org)
...

现在目录知道了关系。

>>> len(catalog)
13
>>> root['dummy'] = Organization('Foo')
>>> root['dummy'] in catalog
False
>>> orgs['Y3L4 Proj'] in catalog
True

此外，现在我们可以进行搜索。为此，我们可以使用目录提供的某些标记方法。最常用的是tokenizeQuery。它接受未标记的值的查询，并将它们转换为标记的值。

>>> Ynod_SAs_id = registry.getId(orgs['Ynod SAs'])
>>> catalog.tokenizeQuery({None: orgs['Ynod SAs']}) == {
...     None: Ynod_SAs_id}
True
>>> Zookd_SAs_id = registry.getId(orgs['Zookd SAs'])
>>> Zookd_Devs_id = registry.getId(orgs['Zookd Devs'])
>>> catalog.tokenizeQuery(
...     {None: zc.relation.catalog.any(
...         orgs['Zookd SAs'], orgs['Zookd Devs'])}) == {
...     None: zc.relation.catalog.any(Zookd_SAs_id, Zookd_Devs_id)}
True

当然，现在仅使用‘部分’进行此操作有点愚蠢，因为它不会在关系目录中更改（因为我们已讨论，转储和加载都是None）。

>>> catalog.tokenizeQuery({'part': Ynod_SAs_id}) == {
...     'part': Ynod_SAs_id}
True
>>> catalog.tokenizeQuery(
...     {'part': zc.relation.catalog.any(Zookd_SAs_id, Zookd_Devs_id)}
...     ) == {'part': zc.relation.catalog.any(Zookd_SAs_id, Zookd_Devs_id)}
True

tokenizeQuery 方法非常常见，因此我们在示例中将它分配给一个变量。然后我们进行一些搜索。

所以……查找由Ynod Devs监督的关系。

>>> t = catalog.tokenizeQuery
>>> res = list(catalog.findRelationTokens(t({None: orgs['Ynod Devs']})))

OK…我们使用了findRelationTokens，而不是findRelations，因此res现在是一组数字。我们如何将其转换回来？resolveRelationTokens 将做到这一点。

>>> len(res)
3
>>> sorted(catalog.resolveRelationTokens(res))
... # doctest: +NORMALIZE_WHITESPACE
[<Organization instance "Bet Proj">, <Organization instance "Y3L4 Proj">,
 <Organization instance "Ynod Devs">]

resolveQuery 是tokenizeQuery 的镜像：它将标记查询转换为具有“加载”值的查询。

>>> original = {'part': zc.relation.catalog.any(
...                 Zookd_SAs_id, Zookd_Devs_id),
...             None: orgs['Zookd Devs']}
>>> tokenized = catalog.tokenizeQuery(original)
>>> original == catalog.resolveQuery(tokenized)
True

>>> original = {None: zc.relation.catalog.any(
...                 orgs['Zookd SAs'], orgs['Zookd Devs']),
...             'part': Zookd_Devs_id}
>>> tokenized = catalog.tokenizeQuery(original)
>>> original == catalog.resolveQuery(tokenized)
True

同样，tokenizeRelations 是resolveRelationTokens 的镜像。

>>> sorted(catalog.tokenizeRelations(
...     [orgs["Bet Proj"], orgs["Y3L4 Proj"]])) == sorted(
...     registry.getId(o) for o in
...     [orgs["Bet Proj"], orgs["Y3L4 Proj"]])
True

其他标记相关方法如下[17]

• tokenizeValues，返回给定索引名称值的标记的可迭代对象；

• resolveValueTokens，返回给定索引名称标记值的可迭代对象；

• tokenizeRelation，返回给定关系的标记；以及

• resolveRelationToken，它返回给定令牌的关联。

为什么我们不隐藏这些令牌，而是使API更漂亮，而要处理这些令牌呢？通过暴露它们，我们能够实现高效的连接和在其他上下文中的高效使用。例如，如果您使用相同的intid工具在其他目录中进行标记，我们的结果可以与其他目录的结果合并。同样，您可以使用对其他目录的查询结果——或者甚至是查询此目录的早期结果的“连接”——作为这里的查询值。我们将在下一节中探讨这一点。

角色

我们已经设置了组织关系。现在让我们设置角色，并实际上能够回答我们在文档开头描述的问题。

在我们的Roles对象中，角色和主体将简单地是字符串——如果这是一个真实系统，则是ids。组织将是直接的对象引用。

>>> @zope.interface.implementer(IRoles)
... @total_ordering
... class Roles(persistent.Persistent):
...
...     def __init__(self, principal_id, role_ids, organization):
...         self.principal_id = principal_id
...         self.role_ids = BTrees.family32.OI.TreeSet(role_ids)
...         self._organization = organization
...     def getOrganization(self):
...         return self._organization
...     # the rest is for prettier/easier tests
...     def __repr__(self):
...         return "<Roles instance (%s has %s in %s)>" % (
...             self.principal_id, ', '.join(self.role_ids),
...             self._organization.title)
...     def __lt__(self, other):
...         _self = (
...             self.principal_id,
...             tuple(self.role_ids),
...             self._organization.title,
...         )
...         _other = (
...             other.principal_id,
...             tuple(other.role_ids),
...             other._organization.title,
...         )
...         return _self <_other
...     def __eq__(self, other):
...         return self is other
...     def __hash__(self):
...         return 1  # dummy
...

现在让我们向关系目录添加值索引。

>>> catalog.addValueIndex(IRoles['principal_id'], btree=BTrees.family32.OI)
>>> catalog.addValueIndex(IRoles['role_ids'], btree=BTrees.family32.OI,
...                       multiple=True, name='role_id')
>>> catalog.addValueIndex(IRoles['getOrganization'], dump, load,
...                       name='organization')

这些是我们在之前《addValueIndex》中看到的一些略微不同的变体，但都是混合和匹配相同的成分。

作为提醒，这里是我们组织结构

        Ynod Corp Mangement                 Zookd Corp Management
         /      |      \                       /      |      \
  Ynod Devs  Ynod SAs  Ynod Admins  Zookd Admins   Zookd SAs  Zookd Devs
    /      \              \                 /                /         \
Y3L4 Proj  Bet Proj      Ynod Zookd Task Force      Zookd hOgnmd     Zookd Nbd

现在让我们创建并添加一些角色。

>>> principal_ids = [
...     'abe', 'bran', 'cathy', 'david', 'edgar', 'frank', 'gertrude',
...     'harriet', 'ignas', 'jacob', 'karyn', 'lettie', 'molly', 'nancy',
...     'ophelia', 'pat']
>>> role_ids = ['user manager', 'writer', 'reviewer', 'publisher']
>>> get_role = dict((v[0], v) for v in role_ids).__getitem__
>>> roles = root['roles'] = BTrees.family32.IO.BTree()
>>> next = 0
>>> for prin, org, role_ids in (
...     ('abe', orgs['Zookd Corp Management'], 'uwrp'),
...     ('bran', orgs['Ynod Corp Management'], 'uwrp'),
...     ('cathy', orgs['Ynod Devs'], 'w'),
...     ('cathy', orgs['Y3L4 Proj'], 'r'),
...     ('david', orgs['Bet Proj'], 'wrp'),
...     ('edgar', orgs['Ynod Devs'], 'up'),
...     ('frank', orgs['Ynod SAs'], 'uwrp'),
...     ('frank', orgs['Ynod Admins'], 'w'),
...     ('gertrude', orgs['Ynod Zookd Task Force'], 'uwrp'),
...     ('harriet', orgs['Ynod Zookd Task Force'], 'w'),
...     ('harriet', orgs['Ynod Admins'], 'r'),
...     ('ignas', orgs['Zookd Admins'], 'r'),
...     ('ignas', orgs['Zookd Corp Management'], 'w'),
...     ('karyn', orgs['Zookd Corp Management'], 'uwrp'),
...     ('karyn', orgs['Ynod Corp Management'], 'uwrp'),
...     ('lettie', orgs['Zookd Corp Management'], 'u'),
...     ('lettie', orgs['Ynod Zookd Task Force'], 'w'),
...     ('lettie', orgs['Zookd SAs'], 'w'),
...     ('molly', orgs['Zookd SAs'], 'uwrp'),
...     ('nancy', orgs['Zookd Devs'], 'wrp'),
...     ('nancy', orgs['Zookd hOgnmd'], 'u'),
...     ('ophelia', orgs['Zookd Corp Management'], 'w'),
...     ('ophelia', orgs['Zookd Devs'], 'r'),
...     ('ophelia', orgs['Zookd Nbd'], 'p'),
...     ('pat', orgs['Zookd Nbd'], 'wrp')):
...     assert prin in principal_ids
...     role_ids = [get_role(l) for l in role_ids]
...     role = roles[next] = Roles(prin, role_ids, org)
...     role.key = next
...     next += 1
...     catalog.index(role)
...

现在我们可以开始进行搜索[18]。

ophelia的所有角色设置是什么？

>>> sorted(catalog.findRelations({'principal_id': 'ophelia'}))
... # doctest: +NORMALIZE_WHITESPACE
[<Roles instance (ophelia has publisher in Zookd Nbd)>,
 <Roles instance (ophelia has reviewer in Zookd Devs)>,
 <Roles instance (ophelia has writer in Zookd Corp Management)>]

这个答案不需要传递性：我们完成了。

下一个问题。ophelia在何处有“writer”角色？

>>> list(catalog.findValues(
...     'organization', {'principal_id': 'ophelia',
...                        'role_id': 'writer'}))
[<Organization instance "Zookd Corp Management">]

嗯，这是正确的非传递性。我们需要一个传递查询工厂吗？不！这是观察我们在上一节中提到的令牌连接的好机会。这实际上应该是一个两步操作：找到ophelia拥有writer的所有组织，然后找到那个组织所有传递部分。

>>> sorted(catalog.findRelations({None: zc.relation.catalog.Any(
...     catalog.findValueTokens('organization',
...                             {'principal_id': 'ophelia',
...                              'role_id': 'writer'}))}))
... # doctest: +NORMALIZE_WHITESPACE
[<Organization instance "Ynod Zookd Task Force">,
 <Organization instance "Zookd Admins">,
 <Organization instance "Zookd Corp Management">,
 <Organization instance "Zookd Devs">,
 <Organization instance "Zookd Nbd">,
 <Organization instance "Zookd SAs">,
 <Organization instance "Zookd hOgnmd">]

这就对了。

下一个问题。哪些用户在“Zookd Devs”组织中拥有角色？非传递性，这很简单。

>>> sorted(catalog.findValueTokens(
...     'principal_id', t({'organization': orgs['Zookd Devs']})))
['nancy', 'ophelia']

传递性，我们应该进行另一个连接。

>>> org_id = registry.getId(orgs['Zookd Devs'])
>>> sorted(catalog.findValueTokens(
...     'principal_id', {
...         'organization': zc.relation.catalog.any(
...             org_id, *catalog.findRelationTokens({'part': org_id}))}))
['abe', 'ignas', 'karyn', 'lettie', 'nancy', 'ophelia']

这有点尴尬，但它确实有效。

最后一个问题，这也是整个示例开始的问题。

ophelia在“Zookd Nbd”组织中有哪些角色？

>>> list(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'})))
['publisher']

非传递性，这是正确的。但是，传递性，ophelia还有审阅者和作者，这是我们想要快速得到答案的。

然后，我们可以以不同的方式提出问题，再次利用连接。我们将将其设置为一个函数，因为我们将在稍后使用它而无需重复代码。

>>> def getRolesInOrganization(principal_id, org):
...     org_id = registry.getId(org)
...     return sorted(catalog.findValueTokens(
...         'role_id', {
...             'organization': zc.relation.catalog.any(
...                 org_id,
...                 *catalog.findRelationTokens({'part': org_id})),
...             'principal_id': principal_id}))
...
>>> getRolesInOrganization('ophelia', orgs['Zookd Nbd'])
['publisher', 'reviewer', 'writer']

正如您所看到的，因此，只要两个查询中的令牌相同，使用令牌就可以实现有趣的连接。

我们已经探讨了令牌方法和令牌技术，如连接。我们讲述的示例故事可以让我们进入一些更高级的主题，例如查询工厂连接和可以增加其读取速度的搜索索引。

查询工厂连接（Query Factory Joins）

我们可以构建一个使连接自动化的查询工厂。查询工厂是一个可调用的对象，它接受两个参数：一个查询（开始搜索的那个）和目录。工厂要么返回None，表示查询工厂不能用于此查询，要么返回另一个可调用的对象，该对象接受一系列关系。关系链中的最后一个令牌是最新的。内部可调用的输出预期是BTrees.family32.OO.Bucket查询的迭代器，用于从给定关系链进一步搜索。

这是对这个问题的错误方法。

>>> def flawed_factory(query, catalog):
...     if (len(query) == 2 and
...         'organization' in query and
...         'principal_id' in query):
...         def getQueries(relchain):
...             if not relchain:
...                 yield query
...                 return
...             current = catalog.getValueTokens(
...                 'organization', relchain[-1])
...             if current:
...                 organizations = catalog.getRelationTokens(
...                     {'part': zc.relation.catalog.Any(current)})
...                 if organizations:
...                     res = BTrees.family32.OO.Bucket(query)
...                     res['organization'] = zc.relation.catalog.Any(
...                         organizations)
...                     yield res
...         return getQueries
...

这适用于我们的当前示例。

>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'}),
...     queryFactory=flawed_factory))
['publisher', 'reviewer', 'writer']

但是，它不适用于其他类似的查询。

>>> getRolesInOrganization('abe', orgs['Zookd Nbd'])
['publisher', 'reviewer', 'user manager', 'writer']
>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'}),
...     queryFactory=flawed_factory))
[]

oops。

flawed_factory实际上是一个用于更典型关系遍历的有用模式。它从关系到关系再到关系，ophelia已经连接到了最顶层。然而，abe只有最顶层，所以没有进行遍历。

相反，我们可以创建一个修改初始查询的查询工厂。

>>> def factory2(query, catalog):
...     if (len(query) == 2 and
...         'organization' in query and
...         'principal_id' in query):
...         def getQueries(relchain):
...             if not relchain:
...                 res = BTrees.family32.OO.Bucket(query)
...                 org_id = query['organization']
...                 if org_id is not None:
...                     res['organization'] = zc.relation.catalog.any(
...                         org_id,
...                         *catalog.findRelationTokens({'part': org_id}))
...                 yield res
...         return getQueries
...

>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'}),
...     queryFactory=factory2))
['publisher', 'reviewer', 'writer']

>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'}),
...     queryFactory=factory2))
['publisher', 'reviewer', 'user manager', 'writer']

与其他方法相比，这种方法的本质是及物性的：这个查询工厂修改了初始查询，然后不提供更多查询。目前目录在查询没有返回任何结果的情况下始终停止调用查询工厂，因此像flawed_factory这样的方法根本无法解决这类问题。

我们可以将这个查询工厂添加为另一个默认选项。

>>> catalog.addDefaultQueryFactory(factory2)

>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'})))
['publisher', 'reviewer', 'writer']

>>> sorted(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'})))
['publisher', 'reviewer', 'user manager', 'writer']

之前安装的查询工厂仍然可用。

>>> list(catalog.iterDefaultQueryFactories()) == [factory1, factory2]
True

>>> list(catalog.findRelations(
...     {'part': registry.getId(orgs['Y3L4 Proj'])}))
...     # doctest: +NORMALIZE_WHITESPACE
[<Organization instance "Ynod Devs">,
 <Organization instance "Ynod Corp Management">]

>>> sorted(catalog.findRelations(
...     {None: registry.getId(orgs['Ynod Corp Management'])}))
...     # doctest: +NORMALIZE_WHITESPACE
[<Organization instance "Bet Proj">, <Organization instance "Y3L4 Proj">,
 <Organization instance "Ynod Admins">,
 <Organization instance "Ynod Corp Management">,
 <Organization instance "Ynod Devs">, <Organization instance "Ynod SAs">,
 <Organization instance "Ynod Zookd Task Force">]

查询工厂连接的搜索索引

现在我们已经编写了一个封装连接的查询工厂，我们可以使用一个加速它的搜索索引。我们迄今为止只使用了及物搜索索引。现在我们将添加一个不及物搜索索引。

不及物搜索索引通常只需要它应该索引的搜索值名称，可选的结果名称（默认为关系），以及可选的查询工厂。

由于我们正在进行的奇怪的连接技巧，我们需要使用两个额外的选项。我们需要指定在对象被索引时需要更改哪些组织和principal_id值，并指示当组织、principal_id或部分发生变化时应该更新。

getValueTokens指定需要索引的值。它获取索引、所需标记的名称、标记、生成标记更改的目录（它可能不与索引的目录相同）、包含一个字典的源字典，该字典包含将用于标记的值（如果未覆盖它们），以及包含此标记的添加值的字典（键是值名称）、包含此标记的删除值的字典，以及标记是否已被删除。该方法可以返回None，这将使索引保留其默认行为，如果未使用查询工厂，则应正常工作；或返回值的一个可迭代集合。

>>> def getValueTokens(index, name, token, catalog, source,
...                    additions, removals, removed):
...     if name == 'organization':
...         orgs = source.get('organization')
...         if not removed or not orgs:
...             orgs = index.catalog.getValueTokens(
...                 'organization', token)
...             if not orgs:
...                 orgs = [token]
...                 orgs.extend(removals.get('part', ()))
...         orgs = set(orgs)
...         orgs.update(index.catalog.findValueTokens(
...             'part',
...             {None: zc.relation.catalog.Any(
...                 t for t in orgs if t is not None)}))
...         return orgs
...     elif name == 'principal_id':
...         # we only want custom behavior if this is an organization
...         if 'principal_id' in source or index.catalog.getValueTokens(
...             'principal_id', token):
...             return ''
...         orgs = set((token,))
...         orgs.update(index.catalog.findRelationTokens(
...             {'part': token}))
...         return set(index.catalog.findValueTokens(
...             'principal_id', {
...                 'organization': zc.relation.catalog.Any(orgs)}))
...

>>> index = zc.relation.searchindex.Intransitive(
...     ('organization', 'principal_id'), 'role_id', factory2,
...     getValueTokens,
...     ('organization', 'principal_id', 'part', 'role_id'),
...     unlimitedDepth=True)
>>> catalog.addSearchIndex(index)

>>> res = catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'}))
>>> list(res)
['publisher', 'reviewer', 'writer']
>>> list(res)
['publisher', 'reviewer', 'writer']

>>> res = catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'}))
>>> list(res)
['publisher', 'reviewer', 'user manager', 'writer']
>>> list(res)
['publisher', 'reviewer', 'user manager', 'writer']

[19]

现在我们可以更改和删除关系——组织角色——并使索引保持正确状态。鉴于当前的组织状态——

        Ynod Corp Mangement                 Zookd Corp Management
         /      |      \                       /      |      \
  Ynod Devs  Ynod SAs  Ynod Admins  Zookd Admins   Zookd SAs  Zookd Devs
    /      \              \                 /                /         \
Y3L4 Proj  Bet Proj      Ynod Zookd Task Force      Zookd hOgnmd     Zookd Nbd

——首先，我们将Ynod Devs移至Zookd Devs之下，然后返回。这将短暂地赋予abe和其他人完全的权限。

>>> list(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'})))
[]
>>> orgs['Zookd Devs'].parts.insert(registry.getId(orgs['Ynod Devs']))
1
>>> catalog.index(orgs['Zookd Devs'])
>>> res = catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'}))
>>> list(res)
['publisher', 'reviewer', 'user manager', 'writer']
>>> list(res)
['publisher', 'reviewer', 'user manager', 'writer']
>>> orgs['Zookd Devs'].parts.remove(registry.getId(orgs['Ynod Devs']))
>>> catalog.index(orgs['Zookd Devs'])
>>> list(catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'})))
[]

作为另一个示例，我们将更改abe的角色，并看到它传播到Zookd Nbd。

>>> rels = list(catalog.findRelations(t(
...     {'principal_id': 'abe',
...      'organization': orgs['Zookd Corp Management']})))
>>> len(rels)
1
>>> rels[0].role_ids.remove('reviewer')
>>> catalog.index(rels[0])

>>> res = catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'}))
>>> list(res)
['publisher', 'user manager', 'writer']
>>> list(res)
['publisher', 'user manager', 'writer']

请注意，搜索索引顺序很重要。在我们的情况下，我们的不及物搜索索引依赖于我们的及物索引，因此及物索引需要先来。您希望在名称之前放置及物关系索引。目前，您负责此顺序：很难提出一个可靠的算法来猜测它。

监听器、目录管理和跨关系目录的连接

我们迄今为止的所有示例都是使用单个目录索引两种类型的关系。如果我们想有两个具有同质关系集合的目录呢？这可能感觉更干净，但也引入了一些新的问题。

让我们使用我们当前的目录来组织，删除额外的信息；并为角色创建一个新的目录。

>>> role_catalog = root['role_catalog'] = catalog.copy()
>>> transaction.commit()
>>> org_catalog = catalog
>>> del catalog

我们需要一个稍微不同的查询工厂和稍微不同的搜索索引< cite>getValueTokens函数。我们将编写这些，然后修改我们两个目录的新世界的配置。

我们在这里编写的及物工厂是为角色目录。它需要访问组织目录。我们可以这样做——依靠实用程序，或者从上下文中找到目录。我们将使role_catalog具有一个.org_catalog属性，并依靠它。

>>> role_catalog.org_catalog = org_catalog
>>> def factory3(query, catalog):
...     if (len(query) == 2 and
...         'organization' in query and
...         'principal_id' in query):
...         def getQueries(relchain):
...             if not relchain:
...                 res = BTrees.family32.OO.Bucket(query)
...                 org_id = query['organization']
...                 if org_id is not None:
...                     res['organization'] = zc.relation.catalog.any(
...                         org_id,
...                         *catalog.org_catalog.findRelationTokens(
...                             {'part': org_id}))
...                 yield res
...         return getQueries
...

>>> def getValueTokens2(index, name, token, catalog, source,
...                    additions, removals, removed):
...     is_role_catalog = catalog is index.catalog # role_catalog
...     if name == 'organization':
...         if is_role_catalog:
...             orgs = set(source.get('organization') or
...                        index.catalog.getValueTokens(
...                         'organization', token) or ())
...         else:
...             orgs = set((token,))
...             orgs.update(removals.get('part', ()))
...         orgs.update(index.catalog.org_catalog.findValueTokens(
...             'part',
...             {None: zc.relation.catalog.Any(
...                 t for t in orgs if t is not None)}))
...         return orgs
...     elif name == 'principal_id':
...         # we only want custom behavior if this is an organization
...         if not is_role_catalog:
...             orgs = set((token,))
...             orgs.update(index.catalog.org_catalog.findRelationTokens(
...                 {'part': token}))
...             return set(index.catalog.findValueTokens(
...                 'principal_id', {
...                     'organization': zc.relation.catalog.Any(orgs)}))
...     return ''

如果您正在跟随代码并与原始代码进行比较，您可能会看到这种方法比关系在相同目录中时更干净。

现在我们将修复组织目录 [20]。

这也展示了使用 removeDefaultQueryFactory 和 removeSearchIndex 方法 [21]。

现在我们将设置角色目录 [22]。

新的 role_catalog 索引需要从 org_catalog 更新。我们将使用监听器，这是一个新概念来实现这一点。

>>> org_catalog.addListener(index2)
>>> list(org_catalog.iterListeners()) == [index2]
True

现在 role_catalog 应该能够回答与旧的单个目录方法相同的问题。

>>> t = role_catalog.tokenizeQuery
>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'})))
['publisher', 'user manager', 'writer']

>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'ophelia'})))
['publisher', 'reviewer', 'writer']

我们也可以修改两个目录，同时搜索索引得到维护。

>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'})))
[]
>>> orgs['Zookd Devs'].parts.insert(registry.getId(orgs['Ynod Devs']))
1
>>> org_catalog.index(orgs['Zookd Devs'])
>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'})))
['publisher', 'user manager', 'writer']
>>> orgs['Zookd Devs'].parts.remove(registry.getId(orgs['Ynod Devs']))
>>> org_catalog.index(orgs['Zookd Devs'])
>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Y3L4 Proj'],
...                   'principal_id': 'abe'})))
[]

>>> rels = list(role_catalog.findRelations(t(
...     {'principal_id': 'abe',
...      'organization': orgs['Zookd Corp Management']})))
>>> len(rels)
1
>>> rels[0].role_ids.insert('reviewer')
1
>>> role_catalog.index(rels[0])

>>> res = role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd Nbd'],
...                   'principal_id': 'abe'}))
>>> list(res)
['publisher', 'reviewer', 'user manager', 'writer']

在这里我们添加一个新组织。

>>> orgs['Zookd hOnc'] = org = Organization('Zookd hOnc')
>>> orgs['Zookd Devs'].parts.insert(registry.getId(org))
1
>>> org_catalog.index(orgs['Zookd hOnc'])
>>> org_catalog.index(orgs['Zookd Devs'])

>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd hOnc'],
...                   'principal_id': 'abe'})))
['publisher', 'reviewer', 'user manager', 'writer']

>>> list(role_catalog.findValueTokens(
...     'role_id', t({'organization': orgs['Zookd hOnc'],
...                   'principal_id': 'ophelia'})))
['reviewer', 'writer']

现在我们将移除它。

>>> orgs['Zookd Devs'].parts.remove(registry.getId(org))
>>> org_catalog.index(orgs['Zookd Devs'])
>>> org_catalog.unindex(orgs['Zookd hOnc'])

TODO 确保非传递性副本看起来像我们预期的那样

[23]

简介

本文件假设您已阅读 README.rst 文件，并希望通过示例了解更多。在它中，我们将探索一组关系，以展示与搜索索引和监听器一起工作的大多数方面。它不会解释其他文档已涵盖的主题。它还描述了一个高级用例。

正如我们在其他文档中看到的，关系目录支持搜索索引。它们可以返回任何搜索的结果，如所需。当然，意图是您提供索引以优化其声称的特定搜索。

searchindex 模块提供了一些搜索索引，优化指定的传递性和非传递性搜索。我们在其他文档中已经看到了它们的工作情况。我们将在这个文档中更深入地研究它们。

搜索索引通过接收通过“监听器”接口的消息来自动更新。我们也将探讨这是如何工作的。

本文件中描述的示例检查了一个类似于 zc.revision 或 zc.vault 软件包中的用例：一个关系描述了其他对象的图。因此，这是我们第一个纯粹的外部关系具体示例。

让我们构建一下这个示例故事。想象一下，我们有一个标记的图，通常是一个层次结构，这些标记是整数。关系指定了给定的整数标记与其他整数标记相关，具有包含表示或其他含义。

整数也可能有表示它们代表对象或对象的关系。

这允许我们有一个对象图，其中更改图的某一部分不需要更改其余部分。因此，zc.revision 和 zc.vault 能够有效地模拟具有多个修订版和大量元数据的图。

让我们想象一个简单的层次结构。关系有一个 token 属性和一个 children 属性；子节点指向标记。关系将通过 id 来标识自己。

>>> import BTrees
>>> relations = BTrees.family64.IO.BTree()
>>> relations[99] = None # just to give us a start

>>> class Relation(object):
...     def __init__(self, token, children=()):
...         self.token = token
...         self.children = BTrees.family64.IF.TreeSet(children)
...         self.id = relations.maxKey() + 1
...         relations[self.id] = self
...

>>> def token(rel, self):
...     return rel.token
...
>>> def children(rel, self):
...     return rel.children
...
>>> def dumpRelation(obj, index, cache):
...     return obj.id
...
>>> def loadRelation(token, index, cache):
...     return relations[token]
...

标准的 TransposingTransitiveQueriesFactory 能够很好地处理这一点，因此我们将为我们的索引使用它。

>>> import zc.relation.queryfactory
>>> factory = zc.relation.queryfactory.TransposingTransitive(
...     'token', 'children')
>>> import zc.relation.catalog
>>> catalog = zc.relation.catalog.Catalog(
...     dumpRelation, loadRelation, BTrees.family64.IO, BTrees.family64)
>>> catalog.addValueIndex(token)
>>> catalog.addValueIndex(children, multiple=True)
>>> catalog.addDefaultQueryFactory(factory)

现在让我们快速创建一个层次结构并将其索引化。

>>> for token, children in (
...     (0, (1, 2)), (1, (3, 4)), (2, (10, 11, 12)), (3, (5, 6)),
...     (4, (13, 14)), (5, (7, 8, 9)), (6, (15, 16)), (7, (17, 18, 19)),
...     (8, (20, 21, 22)), (9, (23, 24)), (10, (25, 26)),
...     (11, (27, 28, 29, 30, 31, 32))):
...     catalog.index(Relation(token, children))
...

[25] 这个层次结构是任意的。以下是我们的标记指向子节点的列表

                                 _____________0_____________
                                /                           \
                       ________1_______                ______2____________
                      /                \              /          |        \
               ______3_____            _4_          10       ____11_____   12
              /            \          /   \         / \     / /  |  \ \ \
      _______5_______       6       13     14     25  26  27 28 29 30 31 32
     /       |       \     / \
   _7_      _8_       9   15 16
  / | \    / | \     / \
17 18 19  20 21 22  23 24

12 个关系，标记从 0 到 11，总共有 33 个标记，包括子节点。12 个关系的 id 是从 100 到 111，对应于 0 到 11 的标记。

没有传递性搜索索引，我们可以获取所有传递性结果。这些结果是迭代器。

>>> res = catalog.findRelationTokens({'token': 0})
>>> getattr(res, '__next__') is None
False
>>> getattr(res, '__len__', None) is None
True
>>> sorted(res)
[100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111]
>>> list(res)
[]

>>> res = catalog.findValueTokens('children', {'token': 0})
>>> sorted(res) == list(range(1, 33))
True
>>> list(res)
[]

[26] canFind 也支持传递性搜索，并且会使用传递性搜索索引，下面我们将看到。

>>> catalog.canFind({'token': 1}, targetQuery={'children': 23})
True
>>> catalog.canFind({'token': 2}, targetQuery={'children': 23})
False
>>> catalog.canFind({'children': 23}, targetQuery={'token': 1})
True
>>> catalog.canFind({'children': 23}, targetQuery={'token': 2})
False

findRelationTokenChains 不会改变，但我们会将其包含在讨论和示例中，以展示这一点。

>>> res = catalog.findRelationTokenChains({'token': 2})
>>> chains = list(res)
>>> len(chains)
3
>>> len(list(res))
0

传递搜索索引

现在我们可以添加几个传递性搜索索引。我们首先来谈谈它们。

目前有一种传递性索引，它为传递性查询工厂中的关系和值搜索建立索引。

索引只能在某些条件下使用。

• 搜索不是关系链请求。

• 它没有指定最大深度。

• 未使用过滤器。

如果是一个值搜索，那么如果使用了目标过滤器或目标查询，就不能使用特定值索引，但仍然可以使用基本关系索引。

搜索索引的使用在很大程度上是透明的：设置它们，关系目录将使用它们来处理之前更粗糙的API调用。唯一的不同之处在于，使用索引的结果通常将是BTree结构，而不是迭代器。

当为一个关系添加传递性索引时，您必须指定查询的传递性名称（或名称），同样反向也是如此。我们现在就做这些。

>>> import zc.relation.searchindex
>>> catalog.addSearchIndex(
...     zc.relation.searchindex.TransposingTransitiveMembership(
...         'token', 'children', names=('children',)))

现在我们应该安装了一个搜索索引。

请注意，我们是从父（令牌）到子：这个索引主要设计用于帮助在层次结构中进行传递性成员搜索。使用它来索引父项将带来很多不必要的写入开销。

这里还可以指定一些内容：查询的静态字段进行一些过滤。在这个示例中我们不需要这些。

现在目录如何使用这个索引进行搜索？三种基本方式，具体取决于搜索的类型，关系、值或 canFind。在我们开始深入了解内部之前，让我们验证我们是否得到了预期的结果：正确的答案，而不是迭代器，而是BTree结构。

>>> res = catalog.findRelationTokens({'token': 0})
>>> list(res)
[100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111]
>>> list(res)
[100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111]

>>> res = catalog.findValueTokens('children', {'token': 0})
>>> list(res) == list(range(1, 33))
True
>>> list(res) == list(range(1, 33))
True

>>> catalog.canFind({'token': 1}, targetQuery={'children': 23})
True
>>> catalog.canFind({'token': 2}, targetQuery={'children': 23})
False

[27] 注意，当我们没有索引时通过这些示例的最后一个两个 canFind 示例没有使用索引，所以我们这里不显示：它们的方向对于这个索引是不正确的。

那么这些结果是如何发生的呢？

第一个，findRelationTokens，和最后一个，canFind，是最直接的。索引找到所有与给定查询匹配的关系，非传递性。然后对于每个关系，它查找该令牌的索引传递性结果。最终结果是所有从非传递性搜索中找到的索引结果的并集。canFind 简单地将结果转换为布尔值。

findValueTokens 与上面相同，只是多了一步。在计算关系并集后，该方法返回所有找到的关系请求值的集合的并集。

当关系重新索引时，它将自行维护。

>>> rel = list(catalog.findRelations({'token': 11}))[0]
>>> for t in (27, 28, 29, 30, 31):
...     rel.children.remove(t)
...
>>> catalog.index(rel)

>>> catalog.findValueTokens('children', {'token': 0})
... # doctest: +NORMALIZE_WHITESPACE
LFSet([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
       20, 21, 22, 23, 24, 25, 26, 32])
>>> catalog.findValueTokens('children', {'token': 2})
LFSet([10, 11, 12, 25, 26, 32])
>>> catalog.findValueTokens('children', {'token': 11})
LFSet([32])

>>> rel.children.remove(32)
>>> catalog.index(rel)

>>> catalog.findValueTokens('children', {'token': 0})
... # doctest: +NORMALIZE_WHITESPACE
LFSet([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
       20, 21, 22, 23, 24, 25, 26])
>>> catalog.findValueTokens('children', {'token': 2})
LFSet([10, 11, 12, 25, 26])
>>> catalog.findValueTokens('children', {'token': 11})
LFSet([])

>>> rel.children.insert(27)
1
>>> catalog.index(rel)

>>> catalog.findValueTokens('children', {'token': 0})
... # doctest: +NORMALIZE_WHITESPACE
LFSet([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
       20, 21, 22, 23, 24, 25, 26, 27])
>>> catalog.findValueTokens('children', {'token': 2})
LFSet([10, 11, 12, 25, 26, 27])
>>> catalog.findValueTokens('children', {'token': 11})
LFSet([27])

当索引被复制时，搜索索引也会被复制。

>>> new = catalog.copy()
>>> res = list(new.iterSearchIndexes())
>>> len(res)
1
>>> new_index = res[0]
>>> res = list(catalog.iterSearchIndexes())
>>> len(res)
1
>>> old_index = res[0]
>>> new_index is old_index
False
>>> old_index.index is new_index.index
False
>>> list(old_index.index.keys()) == list(new_index.index.keys())
True
>>> from __future__ import print_function
>>> for key, value in old_index.index.items():
...     v = new_index.index[key]
...     if v is value or list(v) != list(value):
...         print('oops', key, value, v)
...         break
... else:
...     print('good')
...
good
>>> old_index.names is not new_index.names
True
>>> list(old_index.names) == list(new_index.names)
True
>>> for name, old_ix in old_index.names.items():
...     new_ix = new_index.names[name]
...     if new_ix is old_ix or list(new_ix.keys()) != list(old_ix.keys()):
...         print('oops')
...         break
...     for key, value in old_ix.items():
...         v = new_ix[key]
...         if v is value or list(v) != list(value):
...             print('oops', name, key, value, v)
...             break
...     else:
...         continue
...     break
... else:
...     print('good')
...
good

辅助工具

在编写搜索索引和查询工厂时，您通常希望完全访问关系目录数据。我们已经看到了这些工具中的许多

• getRelationModuleTools 获取用于处理关系的BTree工具的字典。

  >>> sorted(catalog.getRelationModuleTools().keys())
  ... # doctest: +NORMALIZE_WHITESPACE
  ['BTree', 'Bucket', 'Set', 'TreeSet', 'difference', 'dump',
   'intersection', 'load', 'multiunion', 'union']
  

  ‘multiunion’ 只在BTree是I*或L*模块时存在。使用 zc.relation.catalog.multiunion 辅助函数，为给定的工具集执行最佳并集。

• getValueModuleTools 对索引值做相同的事情。

  >>> tools = set(('BTree', 'Bucket', 'Set', 'TreeSet', 'difference',
  ...              'dump', 'intersection', 'load', 'multiunion', 'union'))
  >>> tools.difference(catalog.getValueModuleTools('children').keys()) == set()
  True
  

  >>> tools.difference(catalog.getValueModuleTools('token').keys()) == set()
  True
  

• getRelationTokens 可以返回目录中的所有标记。

  >>> len(catalog.getRelationTokens()) == len(catalog)
  True
  

  这也恰好等同于使用空查询的 findRelationTokens。

  >>> catalog.getRelationTokens() is catalog.findRelationTokens({})
  True
  

  它还可以返回与给定查询匹配的所有标记，如果没有匹配则返回 None。

  >>> catalog.getRelationTokens({'token': 0}) # doctest: +ELLIPSIS
  <BTrees.LOBTree.LOTreeSet object at ...>
  >>> list(catalog.getRelationTokens({'token': 0}))
  [100]
  

  这也恰好等同于带有查询、最大深度为 1 且没有其他参数的 findRelationTokens。

  >>> catalog.findRelationTokens({'token': 0}, maxDepth=1) is (
  ...     catalog.getRelationTokens({'token': 0}))
  True
  

  但是，如果没有匹配，findRelationTokens 返回一个空集（因此它始终返回一个可迭代对象）。

  >>> catalog.findRelationTokens({'token': 50}, maxDepth=1)
  LOSet([])
  >>> print(catalog.getRelationTokens({'token': 50}))
  None
  

• getValueTokens 可以返回目录中给定值名称的所有标记。

  >>> list(catalog.getValueTokens('token')) == list(range(12))
  True
  

  这等同于使用名称仅调用 catalog.findValueTokens（或者使用空查询和最大深度为 1）。

  >>> list(catalog.findValueTokens('token')) == list(range(12))
  True
  >>> catalog.findValueTokens('token') is catalog.getValueTokens('token')
  True
  

  它还可以返回给定标记的值。

  >>> list(catalog.getValueTokens('children', 100))
  [1, 2]
  

  这等同于使用名称和查询 {None: token} 调用 catalog.findValueTokens。

  >>> list(catalog.findValueTokens('children', {None: 100}))
  [1, 2]
  >>> catalog.getValueTokens('children', 100) is (
  ...     catalog.findValueTokens('children', {None: 100}))
  True
  

  但是，如果没有匹配，findValueTokens 返回一个空集（因此它始终返回一个可迭代对象）；而 getValueTokens 如果关系没有值（或关系是未知的），则返回 None。

  >>> catalog.findValueTokens('children', {None: 50}, maxDepth=1)
  LFSet([])
  >>> print(catalog.getValueTokens('children', 50))
  None
  

  >>> rel.children.remove(27)
  >>> catalog.index(rel)
  >>> catalog.findValueTokens('children', {None: rel.id}, maxDepth=1)
  LFSet([])
  >>> print(catalog.getValueTokens('children', rel.id))
  None
  

• yieldRelationTokenChains 是用于使用查询工厂的搜索的强力工具。待办事项：描述。

优化关系目录的使用

关于目录，有几种最佳实践和优化机会。

• 尽可能使用整数键的 BTree 集合。它们可以使用 BTrees 的 multiunion 来提高速度。整数的 __cmp__ 是可靠的，并且在 C 中。

• 永远不要使用持久对象作为键。每次需要查看它们时都会导致数据库负载，它们占用内存和对象缓存，并且它们（根据本文写作时的信息）禁用了冲突解决。Intids（或类似）是表示对象的最佳选择，其次是其他不可变的对象，如字符串，然后是 zope.app.keyreferences（或类似）。

• 尽可能在查询中使用多个标记值，特别是在你的传递查询工厂中。

• 在加载和转储标记以及在你的传递查询工厂中使用缓存。

• 尽可能不要加载或转储标记（值本身可能用作标记）。当你有多个标记时，这一点尤为重要：将它们存储在与 zc.relation 模块相同的模块中的 BTree 结构中，用于值。

对于某些操作，特别是当单个关系值有数百或数千个成员时，这些优化可以将一些常见情况的重索引工作速度提高约 100 倍。

最简单（也许也是最无用的）优化是，所有由单个操作生成的转储调用和所有加载调用共享一个按调用类型（转储/加载）和按索引关系值分组的缓存字典。例如，我们可以存储一个 intids 工具，这样我们只需执行一次工具查找，之后只需进行单个字典查找。这是 zc.relationship 的 index.py 中默认的 generateToken 和 resolveToken 函数所做的：看看它们作为示例。

进一步的优化是不加载或转储标记，而是使用可能是标记的值。如果标记在 C 中具有 __cmp__（或等效）功能，这将特别有用，例如内置类型如整数。要指定此行为，您需要显式将索引的属性描述的“加载”和“转储”值设置为 None。

>>> import zope.interface
>>> class IRelation(zope.interface.Interface):
...     subjects = zope.interface.Attribute(
...         'The sources of the relation; the subject of the sentence')
...     relationtype = zope.interface.Attribute(
...         '''unicode: the single relation type of this relation;
...         usually contains the verb of the sentence.''')
...     objects = zope.interface.Attribute(
...         '''the targets of the relation; usually a direct or
...         indirect object in the sentence''')
...

>>> import BTrees
>>> relations = BTrees.family32.IO.BTree()
>>> relations[99] = None # just to give us a start

>>> @zope.interface.implementer(IRelation)
... class Relation(object):
...
...     def __init__(self, subjects, relationtype, objects):
...         self.subjects = subjects
...         assert relationtype in relTypes
...         self.relationtype = relationtype
...         self.objects = objects
...         self.id = relations.maxKey() + 1
...         relations[self.id] = self
...     def __repr__(self):
...         return '<%r %s %r>' % (
...             self.subjects, self.relationtype, self.objects)

>>> def token(rel, self):
...     return rel.token
...
>>> def children(rel, self):
...     return rel.children
...
>>> def dumpRelation(obj, index, cache):
...     return obj.id
...
>>> def loadRelation(token, index, cache):
...     return relations[token]
...

>>> relTypes = ['has the role of']
>>> def relTypeDump(obj, index, cache):
...     assert obj in relTypes, 'unknown relationtype'
...     return obj
...
>>> def relTypeLoad(token, index, cache):
...     assert token in relTypes, 'unknown relationtype'
...     return token
...

>>> import zc.relation.catalog
>>> catalog = zc.relation.catalog.Catalog(
...     dumpRelation, loadRelation)
>>> catalog.addValueIndex(IRelation['subjects'], multiple=True)
>>> catalog.addValueIndex(
...     IRelation['relationtype'], relTypeDump, relTypeLoad,
...     BTrees.family32.OI, name='reltype')
>>> catalog.addValueIndex(IRelation['objects'], multiple=True)
>>> import zc.relation.queryfactory
>>> factory = zc.relation.queryfactory.TransposingTransitive(
...     'subjects', 'objects')
>>> catalog.addDefaultQueryFactory(factory)

>>> rel = Relation((1,), 'has the role of', (2,))
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 1}))
[2]

如果您有单个关系，涉及数百或数千个对象，如果该值是存储给定属性的BTree的“倍数”类型，那么这将是一个巨大的优势。默认的BTree系列是IFBTree；IOBTree也是一个不错的选择，可能适用于某些应用程序。

>>> catalog.unindex(rel)
>>> rel = Relation(
...     BTrees.family32.IF.TreeSet((1,)), 'has the role of',
...     BTrees.family32.IF.TreeSet())
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 1}))
[]
>>> list(catalog.findValueTokens('subjects', {'objects': None}))
[1]

重新索引是可能出现重大改进的地方。以下操作对优化代码进行了锻炼。

>>> rel.objects.insert(2)
1
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 1}))
[2]
>>> rel.subjects = BTrees.family32.IF.TreeSet((3,4,5))
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 3}))
[2]

>>> rel.subjects.insert(6)
1
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 6}))
[2]

>>> rel.subjects.update(range(100, 200))
100
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 100}))
[2]

>>> rel.subjects = BTrees.family32.IF.TreeSet((3,4,5,6))
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 3}))
[2]

>>> rel.subjects = BTrees.family32.IF.TreeSet(())
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 3}))
[]

>>> rel.subjects = BTrees.family32.IF.TreeSet((3,4,5))
>>> catalog.index(rel)
>>> list(catalog.findValueTokens('objects', {'subjects': 3}))
[2]

tokenizeValues和resolveValueTokens在没有加载器和导出器的情况下工作正常——也就是说，它们什么都不做。

>>> catalog.tokenizeValues((3,4,5), 'subjects')
(3, 4, 5)
>>> catalog.resolveValueTokens((3,4,5), 'subjects')
(3, 4, 5)

2.0 (2023-04-05)

• 停止支持Python 2.7、3.5和3.6。[ale-rt]

• 修复对ZODB的依赖，我们只需依赖于BTrees包。参考#11。[ale-rt]

1.2 (2023-03-28)

• 根据PEP-479（修改生成器内的StopIteration处理）调整代码。参见：https://peps.pythonlang.cn/pep-0479。修复#11。[ale-rt]

1.1.post2（2018-06-18）

• 再次尝试通过使用正确的预期元数据语法修复PyPI页面。

1.1.post1（2018-06-18）

• 使用正确的ReST语法修复PyPI页面。

1.1 (2018-06-15)

• 添加对Python 3.5和3.6的支持。

1.0 (2008-04-23)

这是zc.relation包的初始版本。然而，它代表了另一个包，zc.relationship的重构。此包只包含关系索引的修改版本，现在称为目录。重构后的zc.relationship索引依赖于（子类）此目录。zc.relationship还维护一个向后兼容的子类。

此包仅依赖于ZODB、zope.interface和zope.testing软件，可以在标准ZODB数据库内部或外部使用。尽管如此，该软件必须存在（包在ZODB BTrees包上高度依赖）。

如果您想将旧版zc.relationship索引切换到zc.relation目录，请尝试在您的生成脚本中使用此技巧。假设旧索引是old，以下行应创建一个新的zc.relation目录，包含您的旧数据

>>> new = old.copy(zc.relation.Catalog)

为什么现在将相同的基本数据结构称为目录？因为我们暴露了修改数据结构的能力，您真正添加和删除的是索引。将索引放入索引中是没有意义的，但将索引放入目录中是有意义的。因此，名称更改应运而生。

此包中的目录与早期的zc.relationship索引存在几个不兼容性，以及许多新功能。zc.relationship包维护一个向后兼容的子类。以下讨论将zc.relation目录与zc.relationship 1.x索引进行比较。