From 0d8befd79c201fffc49e396253974a6aff66b598 Mon Sep 17 00:00:00 2001
From: Adrian Vogelsgesang <avogelsgesang@tableau.com>
Date: Sat, 18 Sep 2021 17:36:48 +0200
Subject: [PATCH] Document the `metadata.query` method

---
 docs/api-ref.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/samples.md |  1 +
 2 files changed, 50 insertions(+)

diff --git a/docs/api-ref.md b/docs/api-ref.md
index a4e77db76..874449da7 100644
--- a/docs/api-ref.md
+++ b/docs/api-ref.md
@@ -1374,6 +1374,55 @@ Returns the `JobItem` requested.
 ```
 
 
+<br>
+<br>
+
+---
+
+## Metadata
+
+Using the `metadata` endpoint, one can use GraphQL to query metadata on, e.g., workbooks, datasources, the fields contained within them, and the relationships between them.
+
+### Metadata methods
+
+
+The Metadata methods call the [Metadata API](https://help.tableau.com/current/api/metadata_api/en-us/index.html) which is a GraphQL interface allowing to query metadata about objects on the server (workbooks, datasources, ...) and the relationships between them.
+
+
+Source files: server/endpoint/metadata_endpoint.py
+
+<br>
+<br>
+
+
+#### metadata.query
+
+
+```py
+metadata.query(query, variables=None, abort_on_error=False)
+```
+
+Executes a metadata query and returns the result.
+
+
+**Parameters**
+
+Name | Description
+:--- | :---
+`query`          | The GraphQL query
+`variables`      | Variables for the GraphQL query
+`abort_on_error` | Whether to throw an exception on error
+
+
+**Returns**
+
+The method returns the query results as a stucture of `list`s and `dict`s as returned by the `json` package.
+
+
+**Example**
+
+See the `metadata_query.py` sample in the Samples directory.
+
 <br>
 <br>
 
diff --git a/docs/samples.md b/docs/samples.md
index ed6533e18..ab0ce6ef7 100644
--- a/docs/samples.md
+++ b/docs/samples.md
@@ -48,6 +48,7 @@ The following list describes the samples available in the repository:
 * `kill_all_jobs.py` Kills all running jobs.
 * `list.py` Lists all datasources or workbooks of a site.
 * `login.py` Demonstrates logging in to the server with either username/password or personal access token.
+* `metadata_query.py` Uses the metadata API to query information on a published data source.
 * `move_workbook_projects.py` Moves a workbook from one project to another.
 * `move_workbook_sites.py` Downloads a workbook, stores it in-memory, and uploads it to another site.
 * `pagination_sample.py` Uses the Pager generator to iterate over all the items on the server.