Design doc: new search API #9533

stsewd · 2022-08-22T21:20:59Z

Ref:

📚 Documentation previews 📚

User's documentation (docs): https://docs--9533.org.readthedocs.build/en/9533/

Developer's documentation (dev): https://dev--9533.org.readthedocs.build/en/9533/

ericholscher

I should have read the whole document before commenting, sorry! I really like the syntax approach here, but I do want to have a larger vision for our overall search across the whole product. I think there's a lot of good ideas here, but we should address site search as well with this work.

docs/dev/design/new-search-api.rst

ericholscher · 2022-08-24T21:37:42Z

docs/dev/design/new-search-api.rst

+Is this feature useful? Should we implement
+this as a way to filter projects from https://readthedocs.org/dashboard/ instead?
+This will be using just https://docs.djangoproject.com/en/4.0/ref/contrib/postgres/search/
+or ``contains``.


I think this is probably a good solution. Having project search just use the DB, and then ES is only for searching files. I'd want to have a different UX even for it though, if it's not using the same backend...

ericholscher · 2022-08-25T23:48:31Z

@stsewd I'd love to see an update of this document that really focuses on a unified search experience. I feel pretty strongly that that's the next major project we should do with search, basically bringing the live search the dashboard and to docs in a nicer way.

I think the syntax you're proposing is great, and gives us a lot of flexibility around how to expose this to the user.

stsewd · 2022-08-26T00:05:08Z

I'd love to see an update of this document that really focuses on a unified search experience

@ericholscher do you have a preference on #9533 (comment)?

stsewd · 2022-09-01T00:01:42Z

docs/dev/design/new-search-api.rst

+             }
+           },
+           {
+             "type": "domain",


We could also maybe just drop domains from the new API (#9571), but that decision can be made later, since we would just stop returning these type of blocks.

stsewd · 2022-09-01T00:05:01Z

docs/dev/design/new-search-api.rst

+Another approach could be linking to the global search
+with ``project:{project.slug}`` filled in the query.


If we do this, we could do something similar to github, having a global search bar, and offering the scopes depending if you are on a project/organization or not.

Yea, that is what I'm imagining. Basically we just prepend the project slug in project search mode, but the same UX can be used globally.

So, are we okay for now to just redirect to the global search with the filter set when clicking on Search in

or do we want to have the new search bar together with this implementation?

ericholscher

These are good updates 💯

ericholscher · 2022-09-01T15:27:42Z

docs/dev/design/new-search-api.rst

+Another approach could be linking to the global search
+with ``project:{project.slug}`` filled in the query.


Yea, that is what I'm imagining. Basically we just prepend the project slug in project search mode, but the same UX can be used globally.

ericholscher · 2022-09-01T15:28:48Z

docs/dev/design/new-search-api.rst

+~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can keep the project search as is,
+without using the new syntax (since it doesn't make sense there).


I think for .org, we probably want some kind of "explore" functionality. It's not a huge priority, but I think that's the natural outcome of project search & tag data. But outside the scope of this document.

What does "as is" mean here? Is it the same search bar? A different one?

Yeah, the same search bar, as an option

ericholscher · 2022-09-01T15:29:12Z

docs/dev/design/new-search-api.rst

+~~~~~~~~~~~~~~~~~~~~~
+
+Using the same syntax from the API will be allowed,
+by default it will search all projects in .org,


I think we should switch this to searching your projects by default on .org too, but with an obvious for global?

We can start the search with the user:@me filter set, and if you want a global search, you just remove that filter.

Sounds good 👍

ericholscher · 2022-09-01T15:30:23Z

docs/dev/design/new-search-api.rst

+Another approach could be to allow
+filtering by user on .org, this is ``user:stsewd`` or ``user:@me``
+so a user can search all their projects easily.
+We could allow just ``@me`` to start.


This is a neat idea. This is the start of something like collections #3784 that I've talked about for a long time, if we added tag: filtering, for example. We probably want org: filtering too.

These would be definitely great additions! 💯

docs/dev/design/new-search-api.rst

ericholscher · 2022-09-13T18:16:28Z

I think this mostly looks good to me 👍 Time to start trying to build it, and break the JS from the livesearch out 👍

ericholscher · 2022-11-08T19:20:03Z

@stsewd if this is ready, we should merge it, since we're actively implementing it.

humitos

This document looks good to me. I'd love to see the updates from comments reflected into the document and get merged.

I also asked some questions that I'd like some answers. None of them are blocking, I guess.

humitos · 2022-11-09T11:12:34Z

docs/dev/design/new-search-api.rst

+``subprojects:project/version`` (exclusive)
+  This is the same as the above,
+  but it doesn't include the parent project in the results.
+  If we want to include the results from the project, then
+  the query will be ``project:project/latest subprojects:project/latest``.


I like this pattern. It's pretty explicit what the user wants:

project:docs/latest: won't include subprojects at all

subprojects:docs: will include only results from all the subprojects from the docs project

project:docs/latest subprojects:docs: will include results from docs and all its subprojects

BTW, I would name it subproject (singular) to match the other key project and avoid confusions.

I'm implementing the inclusive option of subprojects, but I'm also fine with the exclusive option. @ericholscher thoughts? I did the first because it mimics our current behavior.

I would name it subproject (singular) to match the other key project and avoid confusions.

I think the plural version is more explicit, since the relationship is one to many, and that's the word we use in our code base/documentation.

Plural is the correct, yeah. I re-read it today and it makes sense. In fact, it could also be subprojects_of if we want to be more explicit about its meaning.

docs/dev/design/new-search-api.rst

humitos · 2022-11-09T11:27:14Z

docs/dev/design/new-search-api.rst

+Another approach could be to allow
+filtering by user on .org, this is ``user:stsewd`` or ``user:@me``
+so a user can search all their projects easily.
+We could allow just ``@me`` to start.


These would be definitely great additions! 💯

stsewd · 2022-11-17T14:08:32Z

If there is anything else to keep discussing, we can comment in the implementation PR.

Design doc: new search API

e56e39c

Ref: - #9376 - #8678

stsewd requested a review from a team as a code owner August 22, 2022 21:21

stsewd requested a review from ericholscher August 22, 2022 21:21

auto-assign bot assigned stsewd Aug 22, 2022

ericholscher reviewed Aug 24, 2022

View reviewed changes

Mention possible solutions for CORS

05f8834

Updates

d522164

stsewd commented Sep 1, 2022

View reviewed changes

stsewd requested a review from ericholscher September 1, 2022 00:05

ericholscher reviewed Sep 1, 2022

View reviewed changes

Updates

d31be80

This was referenced Sep 21, 2022

Search: API V3 #9615

Closed

Search: API V3 #9625

Merged

humitos reviewed Nov 9, 2022

View reviewed changes

stsewd added 2 commits November 14, 2022 10:18

Update doc

0851765

Merge branch 'main' into design-doc-new-search-api

551c839

stsewd merged commit fc7f68b into main Nov 17, 2022

stsewd deleted the design-doc-new-search-api branch November 17, 2022 14:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design doc: new search API #9533

Design doc: new search API #9533

stsewd commented Aug 22, 2022 •

edited by github-actions bot

Loading

ericholscher left a comment

ericholscher Aug 24, 2022

ericholscher commented Aug 25, 2022

stsewd commented Aug 26, 2022

stsewd Sep 1, 2022

stsewd Sep 1, 2022

ericholscher Sep 1, 2022

stsewd Sep 1, 2022

ericholscher left a comment

ericholscher Sep 1, 2022

ericholscher Sep 1, 2022

stsewd Sep 1, 2022

ericholscher Sep 1, 2022

stsewd Sep 1, 2022

ericholscher Sep 1, 2022

ericholscher Sep 1, 2022

humitos Nov 9, 2022

ericholscher commented Sep 13, 2022

ericholscher commented Nov 8, 2022

humitos left a comment

humitos Nov 9, 2022

stsewd Nov 14, 2022

humitos Nov 16, 2022

humitos Nov 9, 2022

stsewd commented Nov 17, 2022

		Another approach could be linking to the global search
		with ``project:{project.slug}`` filled in the query.

Design doc: new search API #9533

Design doc: new search API #9533

Conversation

stsewd commented Aug 22, 2022 • edited by github-actions bot Loading

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher commented Aug 25, 2022

stsewd commented Aug 26, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher commented Sep 13, 2022

ericholscher commented Nov 8, 2022

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Nov 17, 2022

stsewd commented Aug 22, 2022 •

edited by github-actions bot

Loading