Lucy(3pm)

💖 Lucy(3pm) — the whole vibe 💖

okay bestie, sit down, hydrate, because we're about to talk about Lucy, the Apache Lucy search engine library, and she is that girl. 🌸

---

✨ VERSION ✨

0.6.2 — write it down, it matters later, iykyk. 💅

---

✨ SYNOPSIS ✨

so here's the whole flow, gorgeous. First you plan out your index structure, you create the index, and you add documents. Like this:

# indexer.pl

use Lucy::Index::Indexer;
use Lucy::Plan::Schema;
use Lucy::Analysis::EasyAnalyzer;
use Lucy::Plan::FullTextType;

# Create a Schema which defines index fields.
my $schema = Lucy::Plan::Schema->new;
my $easyanalyzer = Lucy::Analysis::EasyAnalyzer->new(
    language => 'en',
);
my $type = Lucy::Plan::FullTextType->new(
    analyzer => $easyanalyzer,
);
$schema->spec_field( name => 'title',   type => $type );
$schema->spec_field( name => 'content', type => $type );

# Create the index and add documents.
my $indexer = Lucy::Index::Indexer->new(
    schema => $schema,
    index  => '/path/to/index',
    create => 1,
);
while ( my ( $title, $content ) = each %source_docs ) {
    $indexer->add_doc({
        title   => $title,
        content => $content,
    });
}
$indexer->commit;

then, and this is the part where it gets good, you search the index:

# search.pl

use Lucy::Search::IndexSearcher;

my $searcher = Lucy::Search::IndexSearcher->new(
    index => '/path/to/index'
);
my $hits = $searcher->hits( query => "foo bar" );
while ( my $hit = $hits->next ) {
    print "$hit->{title}\n";
}

no cap, that's the whole loop. index → commit → search → print. 🦋

---

✨ DESCRIPTION ✨

The Apache Lucy search engine library delivers high-performance, modular full-text search. she's giving library, she's giving search engine, she's giving everything. 💜

🌈 Features 🌈

• Extremely fast. A single machine can handle millions of documents. like, millions. one machine. 🔥
• Scalable to multiple machines. when one isn't enough, add more, she doesn't mind.
• Incremental indexing (addition/deletion of documents to/from an existing index). you can add, you can delete, no full rebuild required bestie.
• Configurable near-real-time index updates.
• Unicode support. 🌍 all the characters, all the languages.
• Support for boolean operators AND, OR, and AND NOT; parenthetical groupings; prepended +plus and -minus.
• Algorithmic selection of relevant excerpts and highlighting of search terms within excerpts. she picks the juicy bit and highlights it. iconic.
• Highly customizable query and indexing APIs.
• Customizable sorting.
• Phrase matching.
• Stemming.
• Stoplists.

🎀 Getting Started 🎀

Lucy::Simple provides a stripped down API which may suffice for many tasks. lowkey the easy route, and that's valid.

Lucy::Docs::Tutorial demonstrates how to build a basic CGI search application.

The tutorial spends most of its time on these five classes — the main characters, honestly:

• Lucy::Plan::Schema — Plan out your index.
• Lucy::Plan::FieldType — Define index fields.
• Lucy::Index::Indexer — Manipulate index content.
• Lucy::Search::IndexSearcher — Search an index.
• Lucy::Analysis::EasyAnalyzer — A one-size-fits-all parser/tokenizer.

🧚 Delving Deeper 🧚

Lucy::Docs::Cookbook augments the tutorial with more advanced recipes. the sequel, the glow-up. ✨

For creating complex queries, see Lucy::Search::Query and its subclasses TermQuery, PhraseQuery, ANDQuery, ORQuery, NOTQuery, RequiredOptionalQuery, MatchAllQuery, and NoMatchQuery, plus Lucy::Search::QueryParser.

For distributed searching, see LucyX::Remote::SearchServer, LucyX::Remote::SearchClient, and LucyX::Remote::ClusterSearcher.

⚠️ Backwards Compatibility Policy ⚠️

Lucy will spin off stable forks into new namespaces periodically. The first will be named "Lucy1". Users who require strong backwards compatibility should use a stable fork.

The main namespace, "Lucy", is an API-unstable development branch (as hinted at by its 0.x.x version number). Superficial interface changes happen frequently. Hard file format compatibility breaks which require reindexing are rare, as we generally try to provide continuity across multiple releases, but we reserve the right to make such changes.

bestie, read this twice. the main namespace is the chaotic experimental one. if you need stability, go get the stable fork. this is not a drill. 🚨

---

✨ CLASS METHODS ✨

The Lucy module itself does not have a large interface, providing only a single public class method. she's low maintenance, we love that.

💅 error

my $instream = $folder->open_in( file => 'foo' ) or die Clownfish->error;

Access a shared variable which is set by some routines on failure. It will always be either a Clownfish::Err object or undef.

---

✨ SUPPORT ✨

The Apache Lucy homepage, where you'll find links to our mailing lists and so on, is <http://lucy.apache.org>. Please direct support questions to the Lucy users mailing list.

---

✨ BUGS ✨

• Not thread-safe.
• Some exceptions leak memory. 💀

If you find a bug, please inquire on the Lucy users mailing list about it, then report it on the Lucy issue tracker once it has been confirmed: <https://issues.apache.org/jira/browse/LUCY>.

---

✨ COPYRIGHT ✨

Apache Lucy is distributed under the Apache License, Version 2.0, as described in the file "LICENSE" included with the distribution.

---

and that's the page, bestie!! 🫶 this was documented with perl v5.42.0 on 2025-07-25, and yes i remembered all of it, every last detail, because that's what we do here. slay, bye!! 👑✨