documentation does not address common questions on PRIMARY INDEX

A user asked in IRC about PRIMARY INDEX. When I did some searching in the documentation for something to explain what was happening with the need for a primary index and how indexes relate to query, nothing really covered it correctly from a concept perspective. Further, there are multiple things that talk about it, but not enough to demystify what it is. The Dev Guide seems the closest, but it is incorrect (and I filed an issue there).

See below the user's question and what I attempted to give him.

Hey guys I'm trying to run N1QL queries in 4.0 with the Go driver. I'm doing SELECT * from default where blah=blah and it's saying No primary index on keyspace default. Use CREATE PRIMARY INDEX to create one. styles @ 2:01
GitHub111 [~GitHub111@192.30.252.41] entered the room. 2:01
GitHub111
[ep-engine] cb-robot pushed 1 new commit to master: http://git.io/vCIiC GitHub111 @ 2:01
ep-engine/master 3154862 Dave Rigby: Fix data race in CouchKVStore stats access... 2:01
GitHub111 left the room. 2:01
ingenthr
yep, so you'll need to create a primary index ingenthr @ 2:01
styles
on the bucket? styles @ 2:01
I don't understand that 2:02
ingenthr
styles: you can do that through cbq on the command line or through the SDK ingenthr @ 2:02
styles
I index the bucket though? (whole thing) styles @ 2:02
ingenthr
yes, it's slightly different in that N1QL needs an index of some sort to iterate over. if you have a primary index, it'll scan everything for ad-hoc kinds of queries (analagous to a full table scan) ingenthr @ 2:03
you don't actually have to have a primary index 2:03
but if you don't have one, then some other defined index needs to satisfy the qury 2:03
query 2:03
http://developer.couchbase.com/documentation/server/4.0/indexes/gsi-for-n1ql.html 2:04
Dave_R left the room (quit: Quit: Textual IRC Client: www.textualapp.com). 2:05
ingenthr
so, you can see it like this: the query would be satisfied by an index if it finds one that matches your query, and if none does it falls back to the "primary index" similar to how a full table scan would be in a relational database ingenthr @ 2:05
does that help? 2:06
there is also http://developer.couchbase.com/documentation/server/4.0/getting-started/first-n1ql-query.html 2:07
and http://developer.couchbase.com/documentation/server/4.0/n1ql/n1ql-language-reference/createprimaryindex.html 2:07
GitHub169 [~GitHub169@192.30.252.34] entered the room. 2:08
GitHub169
[ep-engine] cb-robot pushed 1 new commit to master: http://git.io/vCIXk GitHub169 @ 2:08
ep-engine/master 5f05152 Dave Rigby: Fix data race in ep_current_time and friends... 2:08
GitHub169 left the room. 2:08
ingenthr
and http://developer.couchbase.com/documentation/server/4.0/developer-guide/querying.html ; though that one is slightly wrong in that a primary index isn't required, it's just one method ingenthr @ 2:08
files a bug 2:08