feat(docs): Improve documentation about Search

docs/how/search.md

@@ -1,17 +1,60 @@
-# Search Guide
+import FeatureAvailability from '@site/src/components/FeatureAvailability';
 
-## Introduction 
+# About DataHub Search
 
-The search bar is one of the means of finding data in Datahub. In this document, we discuss more effective ways of finding information beyond doing a standard keyword search. This is because keyword searches can return results from almost any part of an entity.
+<!-- All Feature Guides should begin with `About DataHub ` to improve SEO -->
 
-### Search in Specific Fields
+<!-- 
+Update feature availability; by default, feature availabilty is Self-Hosted and Managed DataHub
 
-The following examples are in the format of  
-X: *typical question* :  
+Add in `saasOnly` for Managed DataHub-only features
+ -->
+
+<FeatureAvailability/>
+
+The **search bar** is an important mechnaism for discovering data assets in DataHub. From the search bar, you can find Datasets, Columns, Dashboards, Charts, Data Pipelines, and more. Simply type in a term and press 'enter'. 
+
+<p align="center">
+<img width="70%"  src="https://github.com/datahub-project/static-assets/blob/main/imgs/search-landingpage.png?raw=true" />
+</p>
+
+**Advanced queries** and the **filter sidebar** helps fine tuning queries. For programmatic users Datahub provides a **GraphQL API** as well. 
+
+## Search Setup, Prerequisites, and Permissions
+
+Search is available for all users. Although Search works out of the box, the more relevant data you ingest, the better the results are.
+
+## Using Search
+
+Searching is as easy as typing in relevant business terms and pressing 'enter' to view matching data assets. 
+
+By default, search terms will match against different aspects of a data assets. This includes asset names, descriptions, tags, terms, owners, and even specific attributes like the names of columns in a table. 
+
+
+### Filters
+
+The filters sidebar sits on the left hand side of search results, and lets users find assets by drilling down. You can quickly filter by Data Platform (e.g. Snowflake), Tags, Glossary Terms, Domain, Owners, and more with a single click. 
+
+<p align="center">
+ <img width="70%"  src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/filters_highlighted.png" />
+</p>
+
+### Results
+
+Search results appear ranked by their relevance. In self-hosted DataHub ranking is based on how closely the query matched textual fields of an asset and its metadata. In Managed DataHub, ranking is based on a combination of textual relevance, usage (queries / views), and change frequency. 
+
+With better metadata comes better results. Learn more about ingestion technical metadata here in the [Metadata-ingestion](../architecture/metadata-ingestion.md) guide.
+
+### Advanced queries
+
+The search bar supports advanced queries with pattern matching, logical expressions and filtering by specific field matches.
+
+The following examples are in the format of
+X: *typical question* :
 ```what to key in search bar```.  [sample url](https://example.com)  
 Wildcard characters can be added to the search terms as well. These examples are non exhaustive and using Datasets as a reference.    
 
-I want to:  
+If you want to:  
 1. *Find a dataset with the word **mask** in the name* :  
 ```name: *mask*``` [Sample results](https://demo.datahubproject.io/search?page=1&query=name%3A%20%2Amask%2A)   
 This will return entities with **mask** in the name.  
@@ -37,7 +80,67 @@ Similar to field descriptions, dataset descriptions can be found in 2 aspects, h
 ```browsePaths: *hive*``` [Sample results](https://demo.datahubproject.io/search?page=1&query=browsePaths%3A%20%2Ahive%2A)  
 BrowsePath is stored as a complete string, for instance ```/datasets/prod/hive/SampleKafkaDataset```, hence the need for wildcards on both ends of the term to return a result. 
 
-## Where to find more information?  
+<!--
+## Additional Resources
+
+ Comment out any irrelevant or empty sections -->
+
+### Videos
+
+**What can you do with DataHub?**
+
+<p align="center">
+<iframe width="560" height="315" src="https://www.youtube.com/watch?v=dubrKIcv37c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+</p> 
+
+<!-- 
+NOTE: Find the iframe details in YouTube by going to Share > Embed 
+ -->
+
+### GraphQL
+
+* Full API documentation: [here](../graphql/queries.md#searchacrossentities).
+* You can try out the API on the demo instance's public GraphQL interface: [here](https://demo.datahubproject.io/api/graphiql).  
+
+The same GraphQL API that powers the Search UI can be used
+for integrations and programmatic use-cases. 
+
+```
+# Example query
+{
+  searchAcrossEntities(
+    input: {types: [], query: "*", start: 0, count: 10, filters: [{field: "fieldTags", value: "urn:li:tag:Dimension"}]}
+  ) {
+    start
+    count
+    total
+    searchResults {
+      entity {
+        type
+        ... on Dataset {
+          urn
+          type
+          platform {
+            name
+          }
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+
+### DataHub Blog
+* [Using DataHub for Search & Discovery](https://blog.datahubproject.io/using-datahub-for-search-discovery-fa309089be22)
+
+## FAQ and Troubleshooting
+
+** How are the results ordered? **
+The order of the search results is based on the weight what Datahub gives them based on our search algorithm. The current algorithm in OSS DataHub is based on a text-match score from Elastic Search.
+
+** Where to find more information? **
 The sample queries here are non exhaustive. [The link here](https://demo.datahubproject.io/tag/urn:li:tag:Searchable) shows the current list of indexed fields for each entity inside Datahub. Click on the fields inside each entity and see which field has the tag ```Searchable```.  
 However, it does not tell you the specific attribute name to use for specialized searches. One way to do so is to inspect the ElasticSearch indices, for example:  
 ```curl http://localhost:9200/_cat/indices``` returns all the ES indices in the ElasticSearch container.  
@@ -121,5 +224,16 @@ example information of a dataset:
       },
 ```
 
+<!-- Use the following format:
+
+**Question in bold text**
+
+Response in plain text
+
+-->
+
+*Need more help? Join the conversation in [Slack](http://slack.datahubproject.io)!*
 
+### Related Features
 
+* [Metadata-ingestion](../architecture/metadata-ingestion.md)