This repository is part of the Pelias project. Pelias is an open-source, open-data geocoder originally sponsored by Mapzen. Our official user documentation is here.
Pelias Elasticsearch Schema Definition
This package defines the Elasticsearch schema used by Pelias. Pelias requires quite a few settings for performance and accuracy. This repository contains those settings as well as useful tools to ensure they are applied correctly.
Requirements
See Pelias Software requirements for general Pelias requirements.
Compatibility
If using Elasticsearch 5, ensure you are using Node.js 8.15+ or Node.js 10.15+.
Versions 8.14 and 10.14 fixed a security issue, but in the process caused issues combined with deprecation headers sent by ES5. This precaution will no longer be necessary once Elasticsearch 2 support is removed.
Installation
$ npm install pelias-schema
Usage
create index
./bin/create_index # quick start
drop index
node scripts/drop_index.js; # drop everything
node scripts/drop_index.js --force-yes; # skip warning prompt
reset a single type
This is useful when you want to reset a single type
without wiping the rest of your index
.
node scripts/reset_type.js mytype; # reset a single type
update settings on an existing index
This is useful when you want to add a new analyser or filter to an existing index.
note: it is impossible to change the number_of_shards
for an existing index, this will require a full re-index.
node scripts/update_settings.js; # update index settings
output schema file
Use this script to pretty-print the whole schema file or a single mapping to stdout.
node scripts/output_mapping.js mytype; # single type mapping
node scripts/output_mapping.js; # whole schema file
check all mandatory elasticsearch plugins are correctly installed
Print a list of which plugins are installed and how to install any that are missing.
node scripts/check_plugins.js;
user customizable synonyms files
You may provide your own custom synonyms by editing files in the ./synonyms/
directory.
$ ls -1 synonyms/custom_*
synonyms/custom_admin.txt
synonyms/custom_name.txt
synonyms/custom_street.txt
You must edit the files before running create_index.js
, any changes made to the files will require you to drop and recreate the index before those synonyms are available.
Synonyms are only used at index-time. The filename contains the name of the elasticsearch field which the synonyms will apply. ie. custom_name
will apply to the name.*
fields, custom_street
will apply to the address_parts.name
field and custom_admin
will apply to the parent.*
fields.
see: pelias#273 for more info.
With great power comes great responsibility. Synonyms files are often used as a hammer when a scalpel is required. Please take care with their use and make maintainers aware that you are using custom synonyms when you open support tickets.
NPM Module
The pelias-schema
npm module can be found here:
https://npmjs.org/package/pelias-schema
You can pull down a versioned copy of the pelias schema from npm:
var schema = require('pelias-schema');
console.log( JSON.stringify( schema, null, 2 ) );
Contributing
Please fork and pull request against upstream master on a feature branch.
Pretty please; provide unit tests and script fixtures in the test
directory.
Running Unit Tests
$ npm test
Running Integration Tests
Requires a running elasticsearch server (no other setup required)
$ npm run integration
Running elasticsearch in Docker (for testing purposes)
Download the image and start an elasticsearch docker container:
$ docker run --rm --name elastic-test -p 9200:9200 pelias/elasticsearch:5.6.12
Continuous Integration
Travis tests every release against all supported Node.js versions.