Don't require a filter for a quick search.

[cholmes]

To solve the issues below, do the following:

1. In quick search, make filter a named option (--filter for CLI, search_filter for api), if not supplied then no filtering will take place
2. Change planet data filter to output an empty filter (no filtering) by default so that planet data filter | planet search PSScene --filter - has the same behavior as planet search PSScene - this resolves Possible to create a filter with conflicting rules #704

---

If I try to do a quick search with no filter I get:

% planet data search-quick PSScene                                                              

Usage: planet data search-quick [OPTIONS] ITEM_TYPES FILTER

Try 'planet data search-quick --help' for help.

Error: Missing argument 'FILTER'.

In v1 doing a search without a filter would just show you the latest data.

Right now you can do planet data filter | planet data search-quick SkysatCollect -, since filter outputs {"type": "PermissionFilter", "config": ["assets:download"]} by default.

But then if you didn't want to only search downloadable assets you could do:

planet data filter --permission false | planet data search-quick SkysatCollect - and then you get a failure, since the latter doesn't actually output a filter, it emits nothing.

[jreiberkyle]

hmm... it looks like filter is a required part of the quick-search request body (ref). I tried submitting a quick-search with filter empty and got an error message from the API.

$ curl -u $PL_API_KEY: https://api.planet.com/data/v1/quick-search \
>   -H "Content-Type: application/json" \
>   --request POST \
>   --data '{"filter":{}, "item_types":["Landsat8L1G"]}'

{"field": {"filter.type": [{"message": "'type' is a required property"}]}, "general": []}planet-client-python$> 

[cholmes]

So the behavior now seems to be a bit different, in a3. If you do search with no arguments you get:

 % planet data search        
Usage: planet data search [OPTIONS] ITEM_TYPES [FILTER]
Try 'planet data search --help' for help.

Error: Missing argument 'ITEM_TYPES'.

The [FILTER] to me implies that the filter argument is optional. If you leave it off right now it appears to just 'hang':

(planet-v2-cli) (base) cholmes@x9t37m3hgt requests % planet data search PSScene

Presumably waiting for input of a filter?

It's definitely my strong preference to have filter be optional in the CLI, and for us to just create an empty 'and' filter to send to the server side so it works. I'm for the Python library being a strict 1 to 1 with the actual API, but the CLI should aim to help a user out. In v1 I consistently use requests with no filters, to just see the latest imagery, and I see no 'win' for requiring a user to always include a filter. #682 also shows a user who seems to expect that things would work without a filter.

[jreiberkyle]

Yep, it's waiting for input of a filter via stdin. Here, planet data search command follows the same pattern as planet orders create. That is, in planet orders create, REQUEST is optional and if not provided then it defaults to stdin. This allows for a command such as planet orders request --name test <etc> | planet orders create. And this is the pattern planned for subscriptions, although right now it does not have a default nor a way to create the REQUEST.

In this pattern, the user simply specifies planet data filter | planet data search and they have a search with an empty filter.

If we go with just planet data search and have the default be an empty filter, then users need to remember to include the - or they will be surprised by their filter being ignored - which would happen with planet data filter | planet data search (no -, so default of empty filter is used). In this scenario, to get their filter to be applied, they would need to use planet data filter | planet data search -

I am with you on helping the user, absolutely. And, I also believe there is a benefit to the user when the command defaults are consistent across the clients.

[jreiberkyle]

oh! also, I don't have time to check out #682 today but I will get to it tomorrow.

[cholmes]

Yep, it's waiting for input of a filter via stdin. Here, planet data search command follows the same pattern as planet orders create. That is, in planet orders create, REQUEST is optional and if not provided then it defaults to stdin. This allows for a command such as planet orders request --name test | planet orders create.

I think we should revisit that pattern, we talked about it a bit in #598. Ideally we find a better mechanism that works like 'less' does. But if we can't I lean towards just requiring the -, for consistency with the rest of the commands. I ended up always including it in my examples - it's harder to remember that in a couple cases you don't need it.

[jreiberkyle]

yeah I agree that the way less does it is better - failing helpfully if nothing is piped in. This isn't how click, our CLI backbone, does it so it would take some investigation to assess LOE. Maybe we could create a ticket for changing the CLI handling of stdin to what less does. If we want to address the concern around the "hang", the change to removing - as a default, and requiring - as an argument, would be a very quick and easy fix and I'm also fully on board with that one.

In regard to planet search with no filter specified, where is the concern with the solution that requires a pipe from planet data filter? It has the benefit of making the user be explicit about submitting a massive (and potentially costly to the server?) search request, so is potentially kinder and more protective of our APIs. It also has the benefit of following the pattern of orders and subscriptions of: <command to create request> | <command to submit request>

[cholmes]

If we want to address the concern around the "hang", the change to removing - as a default, and requiring - as an argument, would be a very quick and easy fix and I'm also fully on board with that one.

Yeah, let's just do this one in the short term, I think it'll just be more consistent throughout, to say that our pattern is to always use - for stdin, and then to not have the 'hanging' behavior. I'll try to ticket it next week, or feel free to do so. And then we can circle back on the less way of doing things, see if there's a way to have click work a bit better.

In regard to planet search with no filter specified, where is the concern with the solution that requires a pipe from planet data filter?

To me it's a regression from v1, and was v1 functionality that I used consistently. It lets you most quickly explore the commands, instead of having to 'figure out' piping - to a new user it feels like a weird incantation just to get the search working.

It has the benefit of making the user be explicit about submitting a massive (and potentially costly to the server?) search request, so is potentially kinder and more protective of our APIs.

It's got a limit on by default, so I don't think it's a massive or costly request? And it's the default in v1 of the CLI, so I think if it was hurting our API's then it would have come up before then.

It also has the benefit of following the pattern of orders and subscriptions of: <command to create request> | <command to submit request>

But it wouldn't actually follow that pattern, as the filter command only creates the filter, not the actual request.

[jreiberkyle]

reopened as this is not completely resolved by #654.