README

AskLucy – 用于创建 Lucene 搜索查询的 PHP 库

本项目包含一个易于使用的 PHP 库，用于创建 Lucene 搜索查询。

内容

• 安装
  • 使用 Git 安装
  • 使用 Composer 安装
• 使用方法
  • 创建子句
    • 创建一个词项
    • 创建一个短语
    • 创建一个范围
    • 创建一个复杂查询
  • 字段
    • 将字段设置为词项
    • 将字段设置为短语
    • 将字段设置为范围
    • 在复杂查询中设置字段
  • 运算符
    • 将运算符设置为词项
    • 将运算符设置为短语
    • 将运算符设置为范围
    • 在复杂查询中设置运算符
  • 相关性提升
  • 模糊性
  • 邻近度搜索
  • 范围搜索

安装

使用 Git 安装

git clone https://github.com/XenosEleatikos/AskLucy.git

使用 Composer 安装

该项目可在 Packagist 上找到： https://packagist.org.cn/packages/xenos/asklucy

您可以使用以下命令安装它

composer require xenos/asklucy

使用方法

该库包含提供 __toString() 方法的类。通过使用 (string) 操作符将其实例转换为字符串，您将获得可用于 Lucene 搜索引擎的子句。有关 Lucene 搜索查询语法的更多信息，您可以 阅读官方文档。但以下部分将为您提供构建此类查询所需的所有必要信息。

对 Lucene 搜索引擎的查询由一个或多个用于匹配文档的子句组成。有四种类型的子句

1. 匹配包含单个单词的文档的词项。
2. 匹配包含一系列单词的文档的短语。
3. 匹配包含介于下限和上限之间的值的文档的范围。
4. 包含一个或多个子句的任何类型的复杂查询。

创建子句

创建一个词项

要创建匹配包含单个单词的文档的查询，例如 "word"，只需按照以下方式构建一个新的 Term

<?php
use AskLucy\Lucene;

$term = Lucene::term('word');

查询的字符串表示形式将是

word

创建一个短语

要创建匹配包含一系列单词的子句，例如 "Lucene search"，您可以实例化一个新的 Phrase，如下所示

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('Lucene query');

查询的字符串表示形式将是

"Lucene query"

创建一个范围

要创建匹配包含介于下限和上限之间的值的文档的范围，使用以下边界实例化一个新的 Rage

<?php
use AskLucy\Lucene;

$range = Lucene::range('alpha', 'omega');

查询的字符串表示形式将是

[alpha TO omega]

创建一个复杂查询

要创建包含一个或多个任何类型子句的复杂查询，实例化一个新的 Query 并添加子句

<?php
use AskLucy\Lucene;

$phrase = Lucene::query()
    ->add(Lucene::term('word'))
    ->add(Lucene::phrase('Lucene query'));

查询的字符串表示形式将是

word "Lucene query"

字段

对于所有类型的子句，您可以通过调用 setField() 方法或向工厂方法添加附加参数来指定要搜索的字段。

将字段设置为词项

要搜索包含 "Lucene" 的（名为 "title" 的）字段的文档，请使用以下代码片段

<?php
use AskLucy\Lucene;

$term = Lucene::term('Lucene');
$term->setField('title');

作为快捷方式，您还可以通过向工厂添加第二个参数直接设置字段

<?php
use AskLucy\Lucene;

$term = Lucene::term('Lucene', 'title');

两者都会得到相同的结果

title:Lucene

将字段设置为短语

您可以通过调用方法 setField() 来指定要搜索的字段...

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('Search Engine');
$phrase->setField('title');

... 或者通过向工厂添加第二个参数来设置字段

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('Search Engine', 'title');

结果是一样的

title:"搜索引擎"

将字段设置为范围

通过调用方法 setField() 指定要搜索值范围的字段...

<?php
use AskLucy\Lucene;

$range = Lucene::range('Anna', 'Doro');
$range->setField('name');

... 或者通过向工厂添加第三个参数来设置字段

<?php
use AskLucy\Lucene;

$range = Lucene::range('Anna', 'Doro', 'name');

结果是一样的

name:[Anna TO Dora]

在复杂查询中设置字段

和之前一样，您可以通过调用方法 setField() 来指定搜索字段...

<?php
use AskLucy\Lucene;

$query = Lucene::query()
    ->add(Lucene::term('Lucene'))
    ->add(Lucene::term('Apache'));
$query->setField('title');

... 或者通过向工厂传递参数

<?php
use AskLucy\Lucene;

$query = Lucene::query('title')
    ->add(Lucene::term('Lucene'))
    ->add(Lucene::term('Apache'));

在这两种情况下，查询的字符串表示形式将是

title:(Lucene Apache)

注意，如果设置了多个子句，括号会自动设置。如果您只想为某个子句指定字段，可以这样做

<?php
use AskLucy\Lucene;

$query = Lucene::query()
    ->add(Lucene::term('Lucene', 'title'))
    ->add(Lucene::term('Apache'));

结果将是

title:Lucene Apache

运算符

对于所有类型的子句，您都可以添加运算符来定义匹配是必需的、禁止的或可选的。只需调用 required()、prohibited() 或 optional()。注意，子句默认是可选的，所以调用 optional() 是可选的。但它可以用来覆盖之前设置的运算符。

将运算符设置为词项

要强制使用单词 "PHP"，请使用以下代码片段...

<?php
use AskLucy\Lucene;

$term = Lucene::term('PHP')
    ->required();

... 然后得到

+PHP

要禁止单词 "Java"，这样做...

<?php
use AskLucy\Lucene;

$term = Lucene::term('Java')
    ->prohibited();

... 您将得到

-Java

将运算符设置为短语

您可以通过与术语相同的方式为短语添加运算符。

强制短语必需...

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('Lucene query')
    ->required();

... 并得到字符串表示

+"Lucene 查询"

禁止短语...

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('Java development')
    ->prohibited();

... 然后得到

-"Java 开发"

将运算符设置为范围

将运算符添加到范围与添加到其他类型的子句的方式相同。

强制范围值必需...

<?php
use AskLucy\Lucene;

$range = Lucene::range('Anna', 'Doro')
    ->required();

... 并得到字符串表示

+[Anna TO Doro]

禁止范围值...

<?php
use AskLucy\Lucene;

$range = Lucene::range('Anna', 'Doro')
    ->prohibited();

... 然后得到

-[Anna TO Doro]

在复杂查询中设置运算符

您可以直接将运算符添加到复杂查询，就像添加到术语和短语一样。

<?php
use AskLucy\Lucene;

$phrase = Lucene::query()
    ->add(Lucene::term('Lucene'))
    ->add(Lucene::phrase('search query'))
    ->required();

查询将匹配包含必要 "Lucene" 或 "搜索查询"（或两者）的所有文档。字符串表示形式将是

+(Lucene "搜索查询")

您可以通过使用 Query::shouldHave()、Query::mustHave() 或 Query::mustNotHave() 来代替创建子句、设置运算符并将它们添加到复杂查询，这些方法会自动将 "可选"、"必需" 或 "禁止" 运算符设置到给定的子查询。

<?php
use AskLucy\Lucene;

$query = Lucene::query()
    ->shouldHave(Lucene::term('word'))
    ->mustHave(Lucene::phrase('Lucene query'))
    ->mustNotHave(Lucene::phrase('Java development'));

查询的字符串表示形式将是

word +"Lucene 查询" -"Java 开发"

相关性提升

您可以为任何类型的子句添加一个 "增强" 因子，使其更加相关。只需使用大于零的增强因子调用 boost()。

<?php
use AskLucy\Lucene;

$term = Lucene::term('Lucene');
$term->boost(2.5);

$phrase = Lucene::phrase('search engine')
    ->boost(2);

$query = Lucene::query()
    ->add(Lucene::term('Apache'))
    ->add($term)
    ->add($phrase);

结果将是

Apache Lucene^2.5 "搜索引擎"^2

模糊性

您可以通过调用 Term::fuzzify() 来执行模糊搜索术语。

<?php
use AskLucy\Lucene;

$term = Lucene::term('word')
    ->fuzzify();

查询的字符串表示形式将是

word~

模糊搜索基于 Damerau-Levenshtein 距离，即达到搜索术语允许的单个字符编辑次数。通过使用可选参数，您可以定义该距离

<?php
use AskLucy\Lucene;

$term = Lucene::term('word')
    ->fuzzify(1);

查询的字符串表示形式将是

word~1

查询将还会匹配像 "Ford" 这样的术语，可以通过对搜索术语的单个字符进行编辑来达到。默认值 fuzzify() 为 2，因此 "nerd" 等单词也会被匹配。使用 0 作为参数将禁用模糊搜索，这等同于没有调用 fuzzify()。允许的值是 0、1 和 2。

邻近度搜索

您可以指定一个最大距离来找到在文档中彼此靠近的术语。例如，如果您在五个单词内搜索术语 "search" 和 "term"，创建以下短语

<?php
use AskLucy\Lucene;

$phrase = Lucene::phrase('search term')
    ->setProximity(5);

查询的字符串表示形式将是

"search term"~5

邻近度 0 表示精确匹配，并且作为 Lucene 默认值，不应渲染。邻近度 1 允许单词交换，如 "term search"。

范围搜索

范围匹配包含介于下限和上限之间的值的文档。它们可以是包含或排除边界的。

<?php
use AskLucy\Lucene;

$range = Lucene::range('Alpha', 'Omega')
    ->inclusive();

此子句匹配包含介于 "Alpha" 和 "Omega" 之间的值的文档，包括 "Alpha" 和 "Omega"。子句将以方括号渲染。

从Alpha到Omega

注意，范围默认是包含的，所以您不需要调用Range::inclusive()。您可以通过调用Range::exclusive()使范围不包含边界

<?php
use AskLucy\Lucene;

$range = Lucene::range('Alpha', 'Omega')
    ->exclusive();

该子句将以花括号的形式显示

{Alpha TO Omega}