Clinton Gormley > Elastic-Model-0.27 > Elastic::Manual


Annotate this POD

View/Report Bugs
Source   Latest Release: Elastic-Model-0.50


Elastic::Manual - What is Elastic::Model and how do I use it?


version 0.27


Elastic::Model is a framework to store your Moose objects, which uses Elasticsearch as a NoSQL document store and flexible search engine.

It is designed to make it easy to start using Elasticsearch with minimal extra code, but allows you full access to the rich feature set available in Elasticsearch as soon as you are ready to use it.

For a brief example of how Elastic::Model works, you should start by reading Elastic::Manual::Intro.

WHAT IS Elasticsearch? ^

Elasticsearch is an open-source Lucene-based full-text search engine, and a NoSQL document store / database.

Schema-free and document oriented

Elasticsearch stores your objects as JSON documents. Most Perl objects can be mapped easily to their JSON equivalent.

It is schema free, in that you don't need to define your field/properties/attributes ahead of time; you can just toss it a JSON document and it'll try to autodetect data types and index your doc. That said, the power of full text search comes from the ability to configure your search to suit your data and requirements. Sophisticated options exist to give you complete control over how your data is indexed.


Elasticsearch is a real-time data store (as soon as your document is indexed, it can be retrieved from any node in the cluster) and has near-real-time search. By default, docs become visible to search within 1 second of being indexed.


Elasticsearch is built to scale out of the box. It is easy to start with a single node, and to add new nodes as required, giving you high availability and huge scale. A cluster can scale to hundreds of nodes and terrabytes of data. If a node goes down, the cluster will automatically redistribute and just keep on working.



Start by reading Elastic::Manual::Intro for a gentle introduction to Elastic::Model.


A brief definition of some of the terms used by Elasticsearch and Elastic::Model.


Some things you need to think about when moving from a relational DB to a NoSQL document store like Elasticsearch.


Fine-tuning how the attributes in your Elastic::Doc classes are indexed.


Making attributes in your Elastic::Doc classes unique.


How to reindex your data when you make changes to your attributes.


Using the Elasticsearch Query DSL (and the ElasticSearch::SearchBuilder syntax) to query your documents efficiently.


Commonly used queries


Commonly used filters


Queries and filters for "nested" fields.


Which search method to use with a View, and how to iterate through the results.


Controlling how your attributes are indexed so that they can be queried as you need.


How to use Elastic::Model to go from a small development environment to massive scale.


When and how to use Scopes, an optional in-memory cache (but required if you use weak refs).


This is a new module, so there will probably be bugs, and the API may change in the future.

If you have any suggestions for improvements, or find any bugs, please report them to I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


The full test suite requires a live Elasticsearch cluster to run. CPAN testers doesn't support this. You can see full test results here:!/clintongormley/Elastic-Model/builds.

To run the full test suite locally, run it as:

    perl Makefile.PL
    ES_HOME=/path/to/Elasticsearch make test

Or, if you are happy for any index starting with "myapp" to be deleted, you can start your Elasticsearch server and run it as:

    perl Makefile.PL
    ES='localhost:9200' make test

This is much faster as it doesn't have to restart the server multiple times, but you will lose any indices matching /^myapp.*/.


You can find documentation for this module with the perldoc command.

    perldoc Elastic::Manual

You can also look for information at:


Thanks to Shay Banon, the Elasticsearch author, for producing an amazingly easy to use search engine, to PERLER for writing ElasticSearchX::Model, which was the original inspiration, to FLORA and MSTROUT for encouraging me to do better, and to DOY for guiding me through Moose internals.


Clinton Gormley <>


This software is copyright (c) 2013 by Clinton Gormley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: