From 51326432be8c702cfe0b9554c51194aa74864b6c Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Fri, 10 Apr 2020 08:46:47 -0400
Subject: [PATCH] [DOCS] Add query reference docs template (#52292)

---
 .../query-dsl/_query-template.asciidoc        | 118 ++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 docs/reference/query-dsl/_query-template.asciidoc

diff --git a/docs/reference/query-dsl/_query-template.asciidoc b/docs/reference/query-dsl/_query-template.asciidoc
new file mode 100644
index 00000000000..610978c0d40
--- /dev/null
+++ b/docs/reference/query-dsl/_query-template.asciidoc
@@ -0,0 +1,118 @@
+////
+This is a template for query DSL reference documentation.
+
+To document a new query type, copy this file, remove comments like this, and
+replace "sample" with the appropriate query name.
+
+Ensure the new query docs are linked and included in
+docs/reference/query-dsl.asciidoc
+////
+
+[[query-dsl-sample-query]]
+=== Sample query
+++++
+<titleabbrev>Sample</titleabbrev>
+++++
+
+////
+INTRO
+Include a brief, 1-2 sentence description.
+////
+
+Does a cool thing. For example, it matches `x` to `y`.
+
+[[sample-query-ex-request]]
+==== Example request
+////
+Basic example of a search request consisting of only this query.
+
+Guidelines
+***************************************
+* Don't include the index name in the request path.
+* Don't include common parameters, such as `boost`.
+* For clarity, use the long version of the request body. You can include a
+  short request example in the 'Notes' section.
+* Ensure // TEST[skip:...] comments are removed.
+***************************************
+////
+
+[source,console]
+----
+GET _search
+{
+    "query": {
+        "sample": {
+            "foo": "baz",
+            "bar": true
+        }
+    }
+}
+----
+// TEST[skip: REMOVE THIS COMMENT.]
+
+[[sample-query-params]]
+==== Parameters
+
+////
+Documents each parameter for the query.
+
+Guidelines
+***************************************
+* Use a definition list.
+* End each definition with a period.
+* Include whether the parameter is Optional or Required and the data type.
+* Include default values as the last sentence of the first paragraph.
+* Include a range of valid values, if applicable.
+* If the parameter requires a specific delimiter for multiple values, say so.
+* If the parameter supports wildcards, ditto.
+* For large or nested objects, consider linking to a separate definition list.
+***************************************
+////
+
+`foo`::
+(Required, string)
+A cool thing.
+
+`bar`::
+(Optional, string)
+If `true`, does a cool thing.
+Defaults to `false`.
+
+
+[[sample-query-notes]]
+==== Notes
+////
+Contains extra information about the query, including:
+* Additional examples for parameters or short request bodies.
+* Tips or advice for using the query.
+
+Guidelines
+***************************************
+* For longer sections, consider using the `[%collapsible] macro.
+* Ensure // TEST[skip:...] comments are removed.
+***************************************
+////
+
+===== Avoid using the `sample` query for `text` fields
+
+By default, {es} changes the values of `text` fields during analysis. For
+example, ...
+
+===== Using the `sample` query on time-series data
+
+You can use the `sample` query to perform searches on time-series data.
+For example:
+
+[source,console]
+----
+GET my_time_series_index/_search
+{
+    "query": {
+        "sample": {
+            "foo": "baz",
+            "bar": false
+        }
+    }
+}
+----
+// TEST[skip: REMOVE THIS COMMENT.]
\ No newline at end of file