Update the documentation to reflect the required change of replication strategy when switching to electricsearch?

[AlexisWilke]

On the following page:

https://express-cassandra.readthedocs.io/en/stable/elassandra/

You have an example that looks like this:

{
    clientOptions: {
        // omitted other options for clarity
        elasticsearch: {
            host: 'http://localhost:9200',
            apiVersion: '5.5',
            sniffOnStart: true,
        }
    },
    ormOptions: {
        // omitted other options for clarity
        migration: 'alter',
        manageESIndex: true,
    }
}

If like me you start from the beginning and then follow these instruction, you are likely to leave the default replication strategy to what it was first setup as.

    ormOptions: {
        defaultReplicationStrategy : {
            class: 'SimpleStrategy',
            replication_factor: 1
        },
        migration: 'safe'
    }

Once you try creating the database with the old strategy, it tells you that SimpleStrategy is not possible in this situation (a.k.a. with manageESIndex: true) and you have to change the strategy to NetworkTopologyStrategy instead.

Also the replication_factor parameter does not work with the NetworkTopologyStrategy. Instead we have to define a data center and rack and that's where the replication is defined. In express-cassandra we can specify the name of the data center like so:

        defaultReplicationStrategy : {
            class: 'NetworkTopologyStrategy',
            DC1: 1
        },

I think that the documentation would be greatly enhance if you also explained where the DC1: 1 comes from (a.k.a. the cassandra-rackdc.properties and cassandra-topology.properties files.)

However, what can be confusing is the fact that the replication factor defined in those files is going to be ignored as the number you specify in your express-cassandra definition(s) is going to prevail.

Thank you.

(see also #184 as the reason for this request)

[masumsoft]

@AlexisWilke Yah you are right, the documentation could be improved to avoid the confusion.

I thought the replication strategy is part of cassandra knowledge and described well in cassandra docs. Hence I avoided that part in my docs. Anyways, as it's creating confusion, we can clarify that in the docs. Could you create an MR with the relevant doc changes?

[AlexisWilke]

I found a document about replication here, but did not add the link in your docs. I'm not too sure that's really that good as it does not reference/explain the rack and topology files anyway.

https://docs.datastax.com/en/cassandra/3.0/cassandra/architecture/archDataDistributeReplication.html

Also searching some more, I could not find any documentation about the defaultReplicationStrategy simple object definition in express-cassandra. It looks like that comes from Apollo which is not being maintained anymore. So having this info there may not be enough. i.e. the Tutorial may want to describe the NetworkTopologyStrategy definition too, unless you know of a page that describes such some where? I just couldn't find it with Google...

[masumsoft]

I guess cql reference on create keyspace has examples that explains what to do while setting keyspace replication.

[masumsoft]

@AlexisWilke What do you think about the cql reference link? Does it clarify? If so, you may add this link to #186

[AlexisWilke]

Yes. I think that can help! I was looking for a Node.js example, but we certainly can do with a CQL command. I updated my patch accordingly. Thank you.