apache / apache/couchdb

Couchdb 3.3 Documentation on Query parameters for Search plugin, remove quotes

Open
#3,111 2 comments 0 reactions 0 assignees View on GitHub
beginner-friendly documentation enhancement
Dominant language
Erlang
Stars
7k
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
9

Description

The documentation at https://docs.couchdb.org/en/master/ddocs/search.html#queries includes examples for queries but shows the query= string wrapped in quotes. The parameter is not quoted. If you use it in curl as documented it will hang on the query.

Developers no doubt figure this out but it can be avoided.
Existing documentation examples.

```
GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json

Example of using HTTP to query a global index:

GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json

Example of using the command line to query a partitioned index:

curl https://$HOST:5984/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/
_search/$INDEX_NAME?include_docs=true\&query="*:*"\&limit=1 \

Example of using the command line to query a global index:

curl https://$HOST:5984/$DATABASE/_design/$DDOC/_search/$INDEX_NAME?
include_docs=true\&query="*:*"\&limit=1 \
```

The example of \*:\* is also misleading. It will return the default for the index which is likely to be all _id's in the database. But if an index is specified the value cannot start with either '?' or '*'. Perhaps something like:

```
GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=$index:$searchString&limit=1 HTTP/1.1
Content-Type: application/json

Example of using HTTP to query a global index:

GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=$index:$searchString&limit=1 HTTP/1.1
Content-Type: application/json

Example of using the command line to query a partitioned index:

curl https://$HOST:5984/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/
_search/$INDEX_NAME?include_docs=true\&query=$index:$searchString\&limit=1 \

Example of using the command line to query a global index:

curl https://$HOST:5984/$DATABASE/_design/$DDOC/_search/$INDEX_NAME?
include_docs=true\&query=$index:$searchString\&limit=1 \

NOTE
Using *:* for the index and search string will use the default rule in the search index document. If this is the normal index('default', doc._id); then all documents in the database will be returned. In normal circumstances the search string cannot start with a wildcard (?,*).

```

This should save some needless scratching of heads.

Contributor guide

Open the contributing guide

Research direction

Start with the Search plugin query examples at https://docs.couchdb.org/en/master/ddocs/search.html#queries. Review the HTTP and curl examples against the issue’s notes about quoting and wildcard searches; done means the examples no longer imply that query values should be quoted and clearly explain the *:* behavior and wildcard restriction.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, search
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.