【Python百日进阶-Web开发-Peewee】Day278 - SQLite 扩展（三）

12.2.7 class JSONPath

class JSONPath(field[, path=None])

参数：
field ( JSONField ) – 我们打算访问的字段对象。
path ( tuple ) – 组成 JSON 路径的组件。
一种方便的 Pythonic 表示 JSON 路径的方式，用于 JSONField.

该JSONPath对象实现__getitem__，累积路径组件，它可以将其转换为相应的 json-path 表达式。

getitem（项目）
参数： 物品– 访问子键键或数组索引。
返回： aJSONPath代表新路径。
访问 JSON 数据中的子键或数组索引。返回一个 JSONPath对象，该对象公开了用于读取或修改 JSON 对象的特定部分的便捷方法。

例子：

# If metadata contains {"tags": ["list", "of", "tags"]}, we can
# extract the first tag in this way:
first_tag = Post.metadata['tags'][0]
query = (Post
         .select(Post, first_tag.alias('first_tag'))
         .order_by(first_tag))

set(value[, as_json=None])

参数：
value – 标量值、列表或字典。
as_json ( bool ) – 强制将值视为 JSON，在这种情况下，它将预先在 Python 中序列化为 JSON。默认情况下，列表和字典被视为要序列化的 JSON，而字符串和整数则按原样传递。
在 JSON 数据中的给定位置设置值。

使用 json1 扩展中的json_set()函数。

update(value)

参数： 数据– 一个标量值、列表或字典，用于与 JSON 数据中给定位置的数据合并。要删除特定键，请将该键设置None为更新的数据中。
使用 RFC-7396 MergePatch 算法将新数据合并到 JSON 值中，以data针对列数据应用补丁（参数）。MergePatch 可以添加、修改或删除 JSON 对象的元素，这意味着它是和update()的通用替换。MergePatch 将 JSON 数组对象视为原子对象，因此不能附加到数组，也不能修改数组的单个元素。set()remove()update()

有关更多信息和示例，请参阅 SQLite json_patch() 函数文档。

remove()

删除存储在 JSON 数据中给定位置的数据。

使用 json1 扩展中的json_type函数。

json_type()

返回一个字符串，该字符串标识存储在 JSON 数据中给定位置的值的类型。

返回的类型将是以下之一：

• object
• array
• integer
• real
• true
• false
• text
• null <– 字符串“null”表示实际的 NULL 值
• NULL <– 实际的 NULL 值表示未找到路径
  使用 json1 扩展中的json_type 函数。

length()

返回存储在 JSON 数据中给定位置的数组的长度。

使用 json1 扩展中的json_array_length 函数。

children()

在给定位置公开 JSON 对象的直接后代的表值函数。另请参阅JSONField.children()。

tree()

以递归方式在给定位置公开 JSON 对象的所有后代的表值函数。另请参阅JSONField.tree()。

12.2.8 class SearchField

class SearchField([unindexed=False[, column_name=None]])

用于表示全文搜索虚拟表的模型上的列的字段类。全文搜索扩展禁止对列指定任何类型或约束。此行为由 强制执行 SearchField，如果尝试任何与全文搜索扩展不兼容的配置，则会引发异常。

文档搜索索引的示例模型（时间戳存储在表中，但其数据不可搜索）：

class DocumentIndex(FTSModel):
    title = SearchField()
    content = SearchField()
    tags = SearchField()
    timestamp = SearchField(unindexed=True)

match（term）

参数： term( str ) – 全文搜索查询/术语
返回： aExpression对应于MATCH 运算符。
Sqlite 的全文搜索支持搜索整个表，包括所有索引列，或搜索单个列。该 match()方法可用于将搜索限制为单个列：

class SearchIndex(FTSModel):
    title = SearchField()
    body = SearchField()

# Search *only* the title field and return results ordered by
# relevance, using bm25.
query = (SearchIndex
         .select(SearchIndex, SearchIndex.bm25().alias('score'))
         .where(SearchIndex.title.match('python'))
         .order_by(SearchIndex.bm25()))

要改为搜索所有索引列，请使用以下 FTSModel.match()方法：

# Searches *both* the title and body and return results ordered by
# relevance, using bm25.
query = (SearchIndex
         .select(SearchIndex, SearchIndex.bm25().alias('score'))
         .where(SearchIndex.match('python'))
         .order_by(SearchIndex.bm25()))

highlight（left ，right ）

参数：
left ( str ) – 高亮的开始标签，例如’’
right ( str ) – 高亮的结束标签，例如’’
使用MATCH运算符执行搜索时，FTS5 可以返回给定列中突出显示匹配的文本。

# Search for items matching string 'python' and return the title
# highlighted with square brackets.
query = (SearchIndex
         .search('python')
         .select(SearchIndex.title.highlight('[', ']').alias('hi')))

for result in query:
    print(result.hi)

# For example, might print:
# Learn [python] the hard way

snippet（left ，right ，over_length=‘…’，max_tokens=16 ）

参数：
left ( str ) – 高亮的开始标签，例如’’
right ( str ) – 高亮的结束标签，例如’’
over_length ( str ) – 当片段超过最大标记数时要添加或附加的文本。
max_tokens ( int ) – 返回的最大令牌，必须是 1 - 64。
使用MATCH运算符执行搜索时，FTS5 可以返回带有包含给定列中突出显示的匹配项的片段的文本。

# Search for items matching string 'python' and return the title
# highlighted with square brackets.
query = (SearchIndex
         .search('python')
         .select(SearchIndex.title.snippet('[', ']').alias('snip')))

for result in query:
    print(result.snip)

class VirtualModel

用于表示虚拟表的模型类。默认元数据设置略有不同，以匹配虚拟表经常使用的设置。

元数据选项：

arguments- 传递给虚拟表构造函数的参数。
extension_module- 用于虚拟表的扩展名。
options- 在虚拟表中应用的设置字典
构造函数。
primary_key- 默认为False，表示没有主键。
这些都以以下方式组合在一起：

CREATE VIRTUAL TABLE <table_name>
USING <extension_module>
([prefix_arguments, ...] fields, ... [arguments, ...], [options...])

12.2.9 class FTS5Model

class FTS5Model

与FTS5 全文搜索扩展VirtualModel一起使用的子类。

FTS5Model 子类应该正常定义，但是有一些警告：

• FTS5 明确禁止在列上指定任何约束、数据类型或索引。因此，所有列都必须是SearchField.
• FTS5 模型包含一个rowid由 SQLite 自动创建和管理的字段（除非您选择在模型创建期间显式设置它）。此列的查找快速而有效。
• 不支持字段索引和多列索引。
  该FTS5扩展附带了 BM25 排名功能的内置实现。因此，searchandsearch_bm25方法已被覆盖以使用内置排名函数而不是用户定义的函数。

classname fts5_installed()

返回一个布尔值，指示是否安装了 FTS5 扩展。如果未安装，将尝试加载扩展。

classmethod search(term[, weights=None[, with_score=False[, score_alias=‘score’]]])

参数：

• term ( str ) – 要使用的搜索词。
• weights – 列的权重列表，根据列在表中的位置排序。或者，以字段或字段名称为键并映射到值的字典。
• with_score – 分数是否应作为SELECT语句的一部分返回。
• score_alias ( str ) – 用于计算排名分数的别名。这是您将用于访问分数的属性 if with_score=True。
• explicit_ordering ( bool ) – 使用完整的 SQL 函数来计算排名，而不是简单地在 ORDER BY 子句中引用分数别名。
  搜索术语并按匹配质量对结果进行排序的简写方式。该FTS5扩展提供了 BM25 算法的内置实现，用于按相关性对结果进行排名。

更高的分数对应于更好的匹配。

# Simple search.
docs = DocumentIndex.search('search term')
for result in docs:
    print(result.title)

# More complete example.
docs = DocumentIndex.search(
    'search term',
    weights={'title': 2.0, 'content': 1.0},
    with_score=True,
    score_alias='search_score')
for result in docs:
    print(result.title, result.search_score)

classname search_bm25(term[, weights=None[, with_score=False[, score_alias=‘score’]]])

与FTS5，search_bm25()方法相同 search()。

classname rank([col1_weight , col2_weight…coln_weight])

参数： col_weight( float ) - (可选) 赋予模型第 i列的权重。默认情况下，所有列的权重为1.0.
生成一个表达式，该表达式将使用BM25 算法计算并返回搜索匹配的质量。该值可用于对搜索结果进行排序，分数越高，匹配越好。

该rank()函数接受允许您为各个列指定权重的可选参数。如果未指定权重，则认为所有列都具有同等重要性。

query = (DocumentIndex
         .select(
             DocumentIndex,
             DocumentIndex.rank().alias('score'))
         .where(DocumentIndex.match('search phrase'))
         .order_by(DocumentIndex.rank()))

for search_result in query:
    print(search_result.title, search_result.score)

笔记
上面的代码示例等价于调用 search()方法：

query = DocumentIndex.search('search phrase', with_score=True)
for search_result in query:
    print(search_result.title, search_result.score)

classname bm25([col1_weight , col2_weight…coln_weight])

因为 FTS5 提供了对 BM25 的内置支持，所以 bm25()方法与方法相同 rank()。

classname VocabModel([table_type=‘row’|‘col’|‘instance’[,table_name=None]])

参数：

• table_type ( str ) – ‘row’、‘col’ 或 ‘instance’。
• table_name – 词汇表的名称。如果未指定，将为“fts5tablename_v”。
  生成适合访问 FTS5搜索索引对应的词汇表的模型类。