Name

PGXN::API::Searcher - PGXN API full text search interface

Synopsis

use PGXN::API::Searcher;
use JSON;
my $search = PGXN::API::Searcher->new('/path/to/api/root');
encode_json $search->search( query => $query, in => 'docs' );

Description

PGXN is a CPAN-inspired network for distributing extensions for the PostgreSQL RDBMS. All of the infrastructure tools, however, have been designed to be used to create networks for distributing any kind of release distributions and for providing a lightweight static file JSON REST API.

This module encapsulates the PGXN API search functionality. The indexes are created by PGXN::API::Indexer; this module parses search queries, executes them against the appropriate index, and returns the results as a hash suitable for serializing to JSON in response to a request.

To use this module, one must have a path to the API server document root created by PGXN::API. That is, with access to the same file system. It is therefore used by PGXN::API itself to process search requests. It will also be used by WWW::PGXN if its mirror URI is specified as a file: URI.

Chances are, if you want to use the PGXN search API, what you really want to use is WWW::PGXN. This module simply provides the low-level file system access to the search databases used by PGXN::API and WWW::PGXN to provide the search interfaces.

But in case you do want to use this module, here are the gory details.

Interface

Constructor

`new`

my $search = PGXN::API::Searcher->new('/path/to/pgxn/api/root');

Constructs a PGXN::API::Searcher object, pointing it to a valid PGXN::API root directory.

Accessors

`doc_root`

my $doc_root = $search->doc_root;

Returns the path to the document root passed to new().

`parsers`

my $doc_parser = $search->parsers->{docs};

Returns a hash reference of search query parsers. The keys are the names of the indexes, and the values are Lucy::Search::QueryParser objects.

Instance Method

`search`

my $results = $search->search( in => 'docs', query => $q );

Queries the specified index and returns a hash reference with the results. The parameters supported in the hash reference second argument are:

query: The search query. See Lucy::Search::QueryParser for the supported syntax of the query. Required.
in: The name of the search index in which to run the query. The default is "docs". The possible values are covered below.
offset: How many hits to skip before showing results. Defaults to 0.
limit: Maximum number of hits to return. Defaults to 50 and may not be greater than 1024.

The results will be returned as a hash with the following keys:

query: The query string. Same value as the query parameter.
limit: Maximum number of records returned. Same as the limit parameter unless it exceeds 1024, in which case it will be the default value, 50.
offset: The number of hits skipped.
count: The total count of hits, without regard to limit or offset. Use for laying out pagination links.
hits: An array of hash references. These constitute the search results. The keys in the hashes depend on which index was searched. See below for that information.

The structure of the hits hash reference depends on which index is specified via the index parameter. The possible values are:

docs

Full text indexing of PGXN documentation. The hits hashes will have the following keys:

title: The document title.
abstract: The document abstract.
excerpt: An excerpt from the document with the search keywords highlighted in <<strong> > tags.
dist: The name of the distribution in which the document is found.
version: The version of the distribution in which the document is found.
docpath: The path to the document within the distribution.
date: The distribution date.
user: The nickname of the user who created the distribution.
user_name: The full name of the user who created the distribution.

dists

Full text search of PGXN distributions. The hits hashes will have the following keys:

name: The name of the distribution.
version: The distribution version.
excerpt: An excerpt from the distribution with the search keywords highlighted in <strong> tags.
abstract: The distribution abstract.
date: The distribution date.
user: The nickname of the user who created the distribution.
user_name: The full name of the user who created the distribution.

extensions

Full text search of PGXN extensions. The hits hashes will have the following keys:

name: The name of the extension.
excerpt: An excerpt from the extension with the search keywords highlighted in <strong> tags.
abstract: The extension abstract.
dist: The name of the distribution in which the extension is found.
version: The version of the distribution in which the extension is found.
docpath: The path to the extension's documentation within the distribution. This is the same format as used for the "docpath" key in docs results, and as used by the "htmldoc" URI template.
date: The distribution date.
user: The nickname of the user who created the distribution.
user_name: The full name of the user who created the distribution.

users

Full text search of PGXN users. The hits hashes will have the following keys:

user: The user's nickname.
name: The user's full name.
uri: The user's URI
excerpt: An excerpt from the user with the search keywords highlighted in <<strong> > tags.

tags

Full text search of PGXN tags. The hits hashes will have the following keys:

name: The tag name.

Support

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Please file bug reports via GitHub Issues.

Author

David E. Wheeler <david@justatheory.com>

Copyright and License

This module is free software; you can redistribute it and/or modify it under the PostgreSQL License.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

In no event shall David E. Wheeler be liable to any party for direct, indirect, special, incidental, or consequential damages, including lost profits, arising out of the use of this software and its documentation, even if David E. Wheeler has been advised of the possibility of such damage.

David E. Wheeler specifically disclaims any warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The software provided hereunder is on an "as is" basis, and David E. Wheeler has no obligations to provide maintenance, support, updates, enhancements, or modifications.

To install PGXN::API::Searcher, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PGXN::API::Searcher

CPAN shell

perl -MCPAN -e shell
install PGXN::API::Searcher

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)