diff --git a/.gitignore b/.gitignore index 90ac70d93dd8..d6ecf2b79524 100644 --- a/.gitignore +++ b/.gitignore @@ -27,4 +27,4 @@ README integration-tests/gen-scripts/ /bin/ *.hprof -*.ipynb_checkpoints/ \ No newline at end of file +**/.ipynb_checkpoints/ diff --git a/docs/tutorials/tutorial-jupyter-index.md b/docs/tutorials/tutorial-jupyter-index.md new file mode 100644 index 000000000000..233b9fda50f5 --- /dev/null +++ b/docs/tutorials/tutorial-jupyter-index.md @@ -0,0 +1,71 @@ +--- +id: tutorial-jupyter-index +title: "Jupyter Notebook tutorials" +--- + + + + + +You can try out the Druid APIs using the Jupyter Notebook-based tutorials. These tutorials provide snippets of Python code that you can use to run calls against the Druid API to complete the tutorial. + +## Prerequisites + +Make sure you meet the following requirements before starting the Jupyter-based tutorials: + +- Python 3 + +- The `requests` package for Python. For example, you can install it with the following command: + + ```bash + pip3 install requests + ``` + +- JupyterLab (recommended) or Jupyter Notebook running on a non-default port. By default, Druid and Jupyter both try to use port `8888,` so start Jupyter on a different port. + + - Install JupyterLab or Notebook: + + ```bash + # Install JupyterLab + pip3 install jupyterlab + # Install Jupyter Notebook + pip3 install notebook + ``` + - Start Jupyter + - JupyterLab + ```bash + # Start JupyterLab on port 3001 + jupyter lab --port 3001 + ``` + - Jupyter Notebook + ```bash + # Start Jupyter Notebook on port 3001 + jupyter notebook --port 3001 + ``` + +- An available Druid instance. You can use the `micro-quickstart` configuration described in [Quickstart (local)](./index.md). The tutorials assume that you are using the quickstart, so no authentication or authorization is expected unless explicitly mentioned. + +## Tutorials + +The notebooks are located in the [apache/druid repo](https://github.com/apache/druid/tree/master/examples/quickstart/jupyter-notebooks/). You can either clone the repo or download the notebooks you want individually. + +The links that follow are the raw GitHub URLs, so you can use them to download the notebook directly, such as with `wget`, or manually through your web browser. Note that if you save the file from your web browser, make sure to remove the `.txt` extension. + +- [Introduction to the Druid API](https://raw.githubusercontent.com/apache/druid/master/examples/quickstart/jupyter-notebooks/api-tutorial.ipynb) walks you through some of the basics related to the Druid API and several endpoints. \ No newline at end of file diff --git a/examples/quickstart/jupyter-notebooks/README.md b/examples/quickstart/jupyter-notebooks/README.md new file mode 100644 index 000000000000..7e5fa2becaee --- /dev/null +++ b/examples/quickstart/jupyter-notebooks/README.md @@ -0,0 +1,89 @@ +# Jupyter Notebook tutorials for Druid + + + + + +You can try out the Druid APIs using the Jupyter Notebook-based tutorials. These tutorials provide snippets of Python code that you can use to run calls against the Druid API to complete the tutorial. + +## Prerequisites + +Make sure you meet the following requirements before starting the Jupyter-based tutorials: + +- Python 3 + +- The `requests` package for Python. For example, you can install it with the following command: + + ```bash + pip3 install requests + ```` + +- JupyterLab (recommended) or Jupyter Notebook running on a non-default port. By default, Druid and Jupyter both try to use port `8888,` so start Jupyter on a different port. + + - Install JupyterLab or Notebook: + + ```bash + # Install JupyterLab + pip3 install jupyterlab + # Install Jupyter Notebook + pip3 install notebook + ``` + - Start Jupyter: + - JupyterLab + ```bash + # Start JupyterLab on port 3001 + jupyter lab --port 3001 + ``` + - Jupyter Notebook + ```bash + # Start Jupyter Notebook on port 3001 + jupyter notebook --port 3001 + ``` + +- An available Druid instance. You can use the `micro-quickstart` configuration described in [Quickstart (local)](../../../docs/tutorials/index.md). The tutorials assume that you are using the quickstart, so no authentication or authorization is expected unless explicitly mentioned. + +## Tutorials + +The notebooks are located in the [apache/druid repo](https://github.com/apache/druid/tree/master/examples/quickstart/jupyter-notebooks/). You can either clone the repo or download the notebooks you want individually. + +The links that follow are the raw GitHub URLs, so you can use them to download the notebook directly, such as with `wget`, or manually through your web browser. Note that if you save the file from your web browser, make sure to remove the `.txt` extension. + +- [Introduction to the Druid API](api-tutorial.ipynb) walks you through some of the basics related to the Druid API and several endpoints. + +## Contributing + +If you build a Jupyter tutorial, you need to do a few things to add it to the docs in addition to saving the notebook in this directory. The process requires two PRs to the repo. + +For the first PR, do the following: + +1. Clear the outputs from your notebook before you make the PR. You can use the following command: + + ```bash + jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace ./path/to/notebook/notebookName.ipynb + ``` + +2. Create the PR as you normally would. Make sure to note that this PR is the one that contains only the Jupyter notebook and that there will be a subsequent PR that updates related pages. + +3. After this first PR is merged, grab the "raw" URL for the file from GitHub. For example, navigate to the file in the GitHub web UI and select **Raw**. Use the URL for this in the second PR as the download link. + +For the second PR, do the following: + +1. Update the list of [Tutorials](#tutorials) on this page and in the [ Jupyter tutorial index page](../../../docs/tutorials/tutorial-jupyter-index.md#tutorials) in the `docs/tutorials` directory. +2. Update `tutorial-jupyter-index.md` and provide the URL to the raw version of the file that becomes available after the first PR is merged. diff --git a/website/.spelling b/website/.spelling index c9562c34dfc7..bd7430c31901 100644 --- a/website/.spelling +++ b/website/.spelling @@ -142,6 +142,7 @@ JVMs Joda JsonProperty Jupyter +JupyterLab KMS Kerberized Kerberos diff --git a/website/sidebars.json b/website/sidebars.json index e0fcbf040358..ef291982c7ff 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -23,6 +23,7 @@ "tutorials/docker", "tutorials/tutorial-kerberos-hadoop", "tutorials/tutorial-msq-convert-spec", + "tutorials/tutorial-jupyter-index", "tutorials/tutorial-jdbc" ], "Design": [