Where to define index and node module? A need for better documentation

When I first read through nearly all the documentation last year, I
thought there is a missing bit of information about defining modules.
Now many months later when I actually want to define a some module
info, I still can't find how to define a module using the REST
interface. So far, I have created everything about an index using the
REST interface,

curl -XPOST "http://myNode.mycompany.com:9200/myIndex/?pretty=1" -d '{
settings: {
...
},
mappings: {
}
}'

Therefore when I read

"all the relevant modules settings can be provided when creating an
index (and it is actually the recommended way to configure an index)."
-- http://www.elasticsearch.org/guide/reference/index-modules/

I figured that I'd put more information in my curl commands for a
particular index, but couldn't find how to do this,. I just wrote all
kinds of paragraphs asking about where to put index module definitions
vs. other module info and trying to tease out a few other clues I found
until I finally found on the configuration page
http://www.elasticsearch.org/guide/reference/setup/configuration.html a
section about index settings. It has an example which as far as I can
tell is the only place that provides that syntax for using index-module
YML in a REST command with no mention on the API create index page. It
also says "the format can be either YAML or JSON". Is that a general
comment about all REST commands or just the index creation command?

Maybe the documentation bug is that the page
http://www.elasticsearch.org/guide/reference/modules/
is empty, so contains no overview about modules, where to and how to
define them.

It appears to me that what we need are the following the missing bits of
documentation which I'd like to add:

  1. http://www.elasticsearch.org/guide/reference/modules/
    Mention closer to all the discussion of (non-index) modules that you
    should define these
    http://www.elasticsearch.org/guide/reference/modules/ ) in the
    elasticSearch.yml. Why because you can navigate to the modules page
    without seeing the configuration page nor would I think most people
    would assume configuration is the primary source for how to define
    modules. I'd add some type of overview statement about modules and
    mention that examples are already in the elasticSearch.yml and are
    commented out (assuming all of the discussed settable parameters are
    actually in the elasticsearch.yml file that comes with elasticSearch).

  2. add a set of cross links on both pages between modules (
    http://www.elasticsearch.org/guide/reference/modules/ ) and index
    modules ( http://www.elasticsearch.org/guide/reference/index-modules/ )
    with a brief comment on the differences of the two.

  3. List node.name on the node module page (
    http://www.elasticsearch.org/guide/reference/modules/node.html ) since
    according to the setup page it is a settable value. :slight_smile:

  4. Discuss (on
    http://www.elasticsearch.org/guide/reference/index-modules/_ how index
    module values can and should be declared when creating an index,
    including repeating (or referencing) the key json vs. yml syntax
    distinct as shown in an example on the create index page and
    particularly including a (simple as possible) example showing where to
    put each of of the modules: analysis ("index.analysis"), shard
    allocation ( "index.routing" ), slow log ( "index.search.slowlog"),
    merge ("index.merge"), store ("index.store" and "indicies.store"),
    mapper ("index.mapper"), translog ("index.translog"), cache
    ("indicies.cache" and "index.cache") in combination with "settings" and
    "mappings". The outer "index", "settings" and optional within
    "settings" of the "index" keyword discussion on
    http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index.html
    doesn't at all make it clear where to put any of these other module
    settings.

  5. Create a brief, but separate page in the setup branch of the
    documentation that pulls out the discussion of the interaction between
    the elasticsearch.yml "index.*" settings and explicit create index
    settings from the configuration page, but also gets the developer
    pointed toward the combination of the create index, dynamic mapping,
    index modules, and mappings pages. Of course leaving a link and
    discussion of the new page on the configuration page.

Now that I've waited 7 months and no one "scratched this itch", I think
I'll have to take this one myself, but if anyone else has any
suggestions about tying configuration, index creation, modules etc.
together, particularly for the new comer, please reply.

-Paul

--
You received this message because you are subscribed to the Google Groups "elasticsearch" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elasticsearch+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.