Document selectivity hints

[dimas-b]

stargate/stargate#1134 and stargate/stargate#1138 allow users to provide selectivity hints in Docs API queries.

Swagger nodes seem to offer to little space for a full description of the new query parameter, though, so we should probably add a section about it to the docs.

Selectivity is a value between 0 and 1 (inclusive) that represents the percentage of rows are expected to be matched by this filter.

Example: where={"fieldA": {"$eq": 1, "$selectivity": 0.8}, "fieldB: {"$eq": 2, "$selectivity": 0.5}}

$selectivity values can be specified in the same JSON block that defies the filter operation and its value, as long as there's only one filter operation in enclosed in a JSON object. If more than one filter are applied to the same field and selectivity hints need to be specified, the filters have to be combined using an explicit boolen operator (e.g. $and).

By default, filters that do not have an explicit selectivity hint provided by the query get the selectivity value of 1.0 (the worst possible selectivity).

Stargate Docs API uses selectivity hints to optimize its query plans. The filter with the best selectivity is usually executed first, but the selectivity hints do not completely override the query engine decisions.

The user can utilize the $profile=true query option to see the effects of different selectivity hints on the final query plan.