Search: Help link to ElasticSearch docs

catalog/app/containers/NavBar/Provider.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react'
 import { useHistory, useLocation, useRouteMatch } from 'react-router-dom'
+import * as M from '@material-ui/core'
 
 import * as SearchUIModel from 'containers/Search/model'
 import * as BucketConfig from 'utils/BucketConfig'
@@ -26,9 +27,15 @@ function useSearchUIModel() {
   return React.useContext(SearchUIModel.Context)
 }
 
+interface InputState extends M.InputBaseProps {
+  expanded: boolean
+  focusTrigger: number
+  helpOpen: boolean
+  push: (str: string) => void
+}
+
 interface SearchState {
-  // input: SearchInputProps
-  input: $TSFixMe
+  input: InputState
   onClickAway: () => void
   reset: () => void
   suggestions: ReturnType<typeof Suggestions.use>
@@ -125,6 +132,8 @@ function useSearchState(bucket?: string): SearchState {
     if (expanded || helpOpen) handleCollapse()
   }, [expanded, helpOpen, handleCollapse])
 
+  const push = React.useCallback((str: string) => change(`${value} ${str}`), [value])
+
   const reset = React.useCallback(() => {
     change('')
     // NOTE: wait for location change (making help closed),
@@ -143,6 +152,7 @@ function useSearchState(bucket?: string): SearchState {
       onChange,
       onFocus: handleExpand,
       onKeyDown,
+      push,
       value: value === null ? query : value,
     },
     reset,

catalog/app/containers/NavBar/Search.tsx

@@ -150,13 +150,13 @@ function Search(props: SearchProps) {
   const navbarState = useNavBar()
   if (!navbarState) return <SearchNotAvailable />
   const {
-    input: { helpOpen, ...input },
+    input: { helpOpen, push, ...input },
     onClickAway,
   } = navbarState
 
   return (
     <Container onClickAway={onClickAway}>
-      <Suggestions classes={helpClasses} open={helpOpen} />
+      <Suggestions classes={helpClasses} open={helpOpen} onClick={push} />
       <SearchInput placeholder="Search" {...input} {...props} />
     </Container>
   )

catalog/app/containers/NavBar/Suggestions/Suggestions.tsx

@@ -3,10 +3,14 @@ import { Link } from 'react-router-dom'
 import * as M from '@material-ui/core'
 
 import * as style from 'constants/style'
+import { docs } from 'constants/urls'
+import StyledLink from 'utils/StyledLink'
 
 import { useNavBar } from '../Provider'
 import type { Suggestion } from './model'
 
+const ES_V = '6.7'
+
 const displaySuggestion = (s: Suggestion) => (
   <>
     Search {s.what} {s.where}
@@ -17,15 +21,27 @@ const useSuggestionsStyles = M.makeStyles((t) => ({
   item: {
     paddingLeft: t.spacing(5.5),
   },
+  help: {
+    ...t.typography.caption,
+    borderTop: `1px solid ${t.palette.divider}`,
+    marginTop: t.spacing(1),
+    padding: t.spacing(1, 5.5, 0.5),
+  },
+  helpExample: {
+    borderBottom: `1px dotted ${t.palette.text.primary}`,
+    cursor: 'help',
+  },
 }))
 
 interface SuggestionsProps {
   items: Suggestion[]
   selected: number
+  onClick: (help: string) => void
 }
 
-function SuggestionsList({ items, selected }: SuggestionsProps) {
+function SuggestionsList({ onClick, items, selected }: SuggestionsProps) {
   const classes = useSuggestionsStyles()
+  const examples = { and: 'termA AND termB', regex: '/lmnb[12]/' }
   return (
     <M.List>
       {items.map((item, index) => (
@@ -40,6 +56,29 @@ function SuggestionsList({ items, selected }: SuggestionsProps) {
           <M.ListItemText primary={displaySuggestion(item)} />
         </M.MenuItem>
       ))}
+      <div className={classes.help}>
+        Quilt uses ElasticSearch {ES_V} query string queries. For example, you can use{' '}
+        <span
+          className={classes.helpExample}
+          onClick={() => onClick(examples.and)}
+          title={`e.g., "${examples.and}"`}
+        >
+          logical operators
+        </span>{' '}
+        and{' '}
+        <span
+          className={classes.helpExample}
+          onClick={() => onClick(examples.regex)}
+          title={`e.g., "${examples.regex}"`}
+        >
+          regular expressions
+        </span>
+        .{' '}
+        <StyledLink href={`${docs}/catalog/searchquery#search-bar`} target="_blank">
+          Learn more
+        </StyledLink>
+        .
+      </div>
     </M.List>
   )
 }
@@ -71,11 +110,13 @@ interface SuggestionsContainerProps {
     contents?: string
   }
   open: boolean
+  onClick: (help: string) => void
 }
 
 export default function SuggestionsContainer({
   classes,
   open,
+  onClick,
 }: SuggestionsContainerProps) {
   const navbarModel = useNavBar()
   if (!navbarModel) return null
@@ -85,7 +126,7 @@ export default function SuggestionsContainer({
   if (!Array.isArray(items) || !items.length) return null
   return (
     <PaperWrapper classes={classes} open={open}>
-      {open && <SuggestionsList items={items} selected={selected} />}
+      {open && <SuggestionsList items={items} selected={selected} onClick={onClick} />}
     </PaperWrapper>
   )
 }

catalog/app/containers/Search/Search.tsx

@@ -7,6 +7,7 @@ import * as FiltersUI from 'components/Filters'
 import Layout from 'components/Layout'
 import * as SearchResults from 'components/SearchResults'
 import Skeleton from 'components/Skeleton'
+import { docs } from 'constants/urls'
 import * as GQL from 'utils/GraphQL'
 import * as JSONPointer from 'utils/JSONPointer'
 import MetaTitle from 'utils/MetaTitle'
@@ -20,6 +21,8 @@ import ResultTypeSelector from './ResultType'
 import { EmptyResults, ResultsSkeleton } from './Results'
 import SortSelector from './Sort'
 
+const ES_V = '6.7'
+
 function useMobileView() {
   const t = M.useTheme()
   return M.useMediaQuery(t.breakpoints.down('sm'))
@@ -256,13 +259,20 @@ function KeywordWildcardFilterWidget({
     },
     [onChange, state],
   )
-  // TODO: link to docs:
-  // https://www.elastic.co/guide/en/elasticsearch/reference/6.7/query-dsl-wildcard-query.html
   return (
     <FiltersUI.TextField
       onChange={handleChange}
       placeholder="Match against (wildcards supported)"
       value={state.wildcard}
+      helperText={
+        <>
+          Quilt uses ElasticSearch {ES_V}.{' '}
+          <StyledLink href={`${docs}/catalog/searchquery#search-bar`} target="_blank">
+            Learn more
+          </StyledLink>
+          .
+        </>
+      }
     />
   )
 }
@@ -277,13 +287,20 @@ function TextFilterWidget({
     },
     [onChange, state],
   )
-  // TODO: link to docs:
-  // https://www.elastic.co/guide/en/elasticsearch/reference/6.7/query-dsl-simple-query-string-query.html
   return (
     <FiltersUI.TextField
       onChange={handleChange}
       placeholder="Search for"
       value={state.queryString}
+      helperText={
+        <>
+          Quilt uses ElasticSearch {ES_V}.{' '}
+          <StyledLink href={`${docs}/catalog/searchquery#search-bar`} target="_blank">
+            Learn more
+          </StyledLink>
+          .
+        </>
+      }
     />
   )
 }

docs/Catalog/SearchQuery.md

@@ -34,9 +34,9 @@ to deep index can be customized per Bucket in the Catalog Admin settings.
 
 ![Example of Admin Bucket indexing options](../imgs/elastic-search-indexing-options.png)
 
-### Navigation Bar
+### Search Bar
 
-The navigation bar on every page in the catalog provides a convenient
+The search bar on every page in the catalog provides a convenient
 shortcut for searching objects and packages in an Amazon S3
 bucket.
 
@@ -47,38 +47,40 @@ The following are all valid search parameters:
 
 **Fields**
 
-- `comment`: Package comment. `comment: TODO`
-- `content`: Object content. `content:Hello`
-- `ext`: Object extension. `ext:*.fastq.gz`
-- `handle`: Package name. `handle:examples\/metadata`
-- `hash`: Package hash. `hash:3192ac1*`
-- `key`: Object key. `key:phase*`
-- `key_text`: Analyzed object key. `key:"phase"`
-- `last_modified`: Last modified date. `last_modified:[2022-02-04 TO
-  2022-02-20]`
-- `metadata`: Package metadata. `metadata:dapi`
-- `size`: Object size in bytes. `size:>=4096`
-- `version_id`: Object version id. `version_id:t.LVVCx*`
-- `pointer_file`: Package revision tag in S3; either "latest" or a top hash. `pointer_file: latest`
-- `package_stats.total_files`: Package total files.
-  `package_stats.total_files:>100`
-- `package_stats.total_bytes`: Package total bytes.
-  `package_stats.total_bytes:<100`
+| Keyword | Description | Example |
+|- | - | - |
+| `comment`| Package comment | `comment:TODO` |
+| `content`| Object content | `content:Hello` |
+| `ext`| Object extension | `ext:*.fastq.gz` |
+| `handle`| Package name | `handle:examples\/metadata` |
+| `hash`| Package hash | `hash:3192ac1*` |
+| `key`| Object key | `key:phase*` |
+| `key_text`| Analyzed object key | `key:"phase"` |
+| `last_modified`| Last modified date | `last_modified:[2022-02-04 TO 2022-02-20]`|
+| `metadata` | Package metadata | `metadata:dapi` |
+| `size` | Object size in bytes | `size:>=4096` |
+| `version_id` | Object version id | `version_id:t.LVVCx*` |
+| `pointer_file` | Package revision tag in S3; either "latest" or a top hash | `pointer_file:latest` |
+| `package_stats.total_files` | Package total files | `package_stats.total_files:>100` |
+| `package_stats.total_bytes` | Package total bytes | `package_stats.total_bytes:<100` |
 
 **Logical operators and grouping**
 
-- `AND`: Conjunction. `a AND b`
-- `OR`: Disjunction. `a OR b`
-- `NOT`: Negation. `NOT a`
-- `_exists_`: Matches any non-null value for the given field. `_exists_: content`
-- `()`: Group terms. `(a AND b) NOT c`
+| Keyword | Description | Example |
+|- | - | - |
+| `AND` | Conjunction | `a AND b` |
+| `OR` | Disjunction | `a OR b` |
+| `NOT` | Negation | `NOT a` |
+| `_exists_` | Matches any non-null value for the given field | `_exists_: content` |
+| `()` | Group terms | `(a AND b) NOT c` |
 
 **Wildcard and regular expressions**
 
-- `*`: Zero or more characters, avoid leading `*` (slows performance).
-  `ext:config.y*ml`
-- `?`: Exactly one character. `ext:React.?sx`
-- `//`: Regular expression (slows performance). `content:/lmnb[12]/`
+| Keyword | Description | Example |
+|- | - | - |
+| `*` | Zero or more characters, avoid leading `*` (slows performance) | `ext:config.y*ml` |
+| `?` | Exactly one character | `ext:React.?sx` |
+| `//` | Regular expression (slows performance) | `content:/lmnb[12]/` |
 
 ### QUERIES > ELASTICSEARCH tab