First pass of documentation in mdBook

.gitignore

@@ -22,4 +22,6 @@ venv
 apache-rat-*.jar
 *rat.txt
 .env
-CHANGELOG.md.bak
+CHANGELOG.md.bak
+
+docs/mdbook/book

docs/mdbook/README.md

@@ -0,0 +1,33 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# DataFusion Book
+
+This folder builds a DataFusion user guide using [mdBook](https://github.com/rust-lang/mdBook).
+
+## Build and run book locally
+
+Build the latest files with `mdbook build`.
+
+Open the book locally by running `open book/index.html`.
+
+## Install mdBook
+
+Download the `mdbook` binary.
+
+Then manually open it, so you have permissions to run it on your Mac.
+
+Add it to your path with a command like this so you can easily run the commands: `mv ~/Downloads/mdbook /Users/matthew.powers/.local/bin`.

docs/mdbook/book.toml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[book]
+authors = ["Apache Arrow <[email protected]>"]
+language = "en"
+multilingual = false
+src = "src"
+title = "DataFusion Book"

docs/mdbook/src/SUMMARY.md

@@ -0,0 +1,24 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# Summary
+
+- [Index](./index.md)
+- [Installation](./installation.md)
+- [Quickstart](./quickstart.md)
+- [Usage](./usage/index.md)
+    - [Create a table](./usage/create-table.md)
+    - [Query a table](./usage/query-table.md)

docs/mdbook/src/index.md

@@ -0,0 +1,43 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# DataFusion Book
+
+DataFusion is a blazing fast query engine that lets you run data analyses quickly and reliably.
+
+DataFusion is written in Rust, but also exposes Python and SQL bindings, so you can easily query data in your langauge of choice.  You don't need to know any Rust to be a happy and productive user of DataFusion.
+
+DataFusion lets you run queries faster than pandas.  Let's compare query runtimes for a 5GB CSV file with 100 million rows of data.
+
+Take a look at a few rows of the data:
+
+```
++-------+-------+--------------+-----+-----+-------+----+----+-----------+
+| id1   | id2   | id3          | id4 | id5 | id6   | v1 | v2 | v3        |
++-------+-------+--------------+-----+-----+-------+----+----+-----------+
+| id016 | id016 | id0000042202 | 15  | 24  | 5971  | 5  | 11 | 37.211254 |
+| id039 | id045 | id0000029558 | 40  | 49  | 39457 | 5  | 4  | 48.951141 |
+| id047 | id023 | id0000071286 | 68  | 20  | 74463 | 2  | 14 | 60.469241 |
++-------+-------+--------------+-----+-----+-------+----+----+-----------+
+```
+
+Suppose you'd like to run the following query: `SELECT id1, sum(v1) AS v1 from the_table GROUP BY id1`.
+
+If you use pandas, then this query will take 43.6 seconds to execute.
+
+It only takes DataFusion 9.8 seconds to execute the same query.
+
+DataFusion is easy to use, powerful, and fast.  Let's learn more!

docs/mdbook/src/installation.md

@@ -0,0 +1,62 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# Installation
+
+DataFusion is easy to install, just like any other Python library.
+
+## Using pip
+
+``` bash
+pip install datafusion
+```
+
+## Conda & JupyterLab setup
+
+This section explains how to install DataFusion in a conda environment with other libraries that allow for a nice Jupyter workflow.  This setup is completely optional.  These steps are only needed if you'd like to run DataFusion in a Jupyter notebook and have an interface like this:
+
+![DataFusion in Jupyter](https://github.com/MrPowers/datafusion-book/raw/main/src/images/datafusion-jupyterlab.png)
+
+Create a conda environment with DataFusion, Jupyter, and other useful dependencies in the `datafusion-env.yml` file:
+
+```
+name: datafusion-env
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.9
+  - ipykernel
+  - nb_conda
+  - jupyterlab
+  - jupyterlab_code_formatter
+  - isort
+  - black
+  - pip
+  - pip:
+    - datafusion
+
+```
+
+Create the environment with `conda env create -f datafusion-env.yml`.
+
+Activate the environment with `conda activate datafusion-env`.
+
+Run `jupyter lab` or open the [JupyterLab Desktop application](https://github.com/jupyterlab/jupyterlab-desktop) to start running DataFusion in a Jupyter notebook.
+
+## Examples
+
+See the [DataFusion Python Examples](https://github.com/apache/arrow-datafusion-python/tree/main/examples) for a variety of Python scripts that show DataFusion in action!

docs/mdbook/src/quickstart.md

@@ -0,0 +1,77 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# DataFusion Quickstart
+
+You can easily query a DataFusion table with the Python API or with pure SQL.
+
+Let's create a small DataFrame and then run some queries with both APIs.
+
+Start by creating a DataFrame with four rows of data and two columns: `a` and `b`.
+
+```python
+from datafusion import SessionContext
+
+ctx = SessionContext()
+
+df = ctx.from_pydict({"a": [1, 2, 3, 1], "b": [4, 5, 6, 7]}, name="my_table")
+```
+
+Let's append a column to this DataFrame that adds columns `a` and `b` with the SQL API.
+
+```
+ctx.sql("select a, b, a + b as sum_a_b from my_table")
+
++---+---+---------+
+| a | b | sum_a_b |
++---+---+---------+
+| 1 | 4 | 5       |
+| 2 | 5 | 7       |
+| 3 | 6 | 9       |
+| 1 | 7 | 8       |
++---+---+---------+
+```
+
+DataFusion makes it easy to run SQL queries on DataFrames.
+
+Now let's run the same query with the DataFusion Python API:
+
+```python
+from datafusion import col
+
+df.select(
+    col("a"),
+    col("b"),
+    col("a") + col("b"),
+)
+```
+
+We get the same result as before:
+
+```
++---+---+-------------------------+
+| a | b | my_table.a + my_table.b |
++---+---+-------------------------+
+| 1 | 4 | 5                       |
+| 2 | 5 | 7                       |
+| 3 | 6 | 9                       |
+| 1 | 7 | 8                       |
++---+---+-------------------------+
+```
+
+DataFusion also allows you to query data with a well-designed Python interface.
+
+Python users have two great ways to query DataFusion tables.

docs/mdbook/src/usage/create-table.md

@@ -0,0 +1,59 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# DataFusion Create Table
+
+It's easy to create DataFusion tables from a variety of data sources.
+
+## Create Table from Python Dictionary
+
+Here's how to create a DataFusion table from a Python dictionary:
+
+```python
+from datafusion import SessionContext
+
+ctx = SessionContext()
+
+df = ctx.from_pydict({"a": [1, 2, 3, 1], "b": [4, 5, 6, 7]}, name="my_table")
+```
+
+Supplying the `name` parameter is optional.  You only need to name the table if you'd like to query it with the SQL API.
+
+You can also create a DataFrame without a name that can be queried with the Python API:
+
+```python
+from datafusion import SessionContext
+
+ctx = SessionContext()
+
+df = ctx.from_pydict({"a": [1, 2, 3, 1], "b": [4, 5, 6, 7]})
+```
+
+## Create Table from CSV
+
+You can read a CSV into a DataFusion DataFrame.  Here's how to read the `G1_1e8_1e2_0_0.csv` file into a table named `csv_1e8`:
+
+```python
+ctx.register_csv("csv_1e8", "G1_1e8_1e2_0_0.csv")
+```
+
+## Create Table from Parquet
+
+You can read a Parquet file into a DataFusion DataFrame.  Here's how to read the `yellow_tripdata_2021-01.parquet` file into a table named `taxi`.
+
+```python
+ctx.register_parquet("taxi", "yellow_tripdata_2021-01.parquet")
+```

docs/mdbook/src/usage/index.md

@@ -0,0 +1,25 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+# Usage
+
+This section shows how to create DataFusion DataFrames from a variety of data sources like CSV files and Parquet files.
+
+You'll learn more about the SQL statements that are supported by DataFusion.
+
+You'll also learn about the DataFusion's Python API for querying data.
+
+The documentation will wrap up with a variety of real-world data processing tasks that are well suited for DataFusion.  The lightning-fast speed and reliable execution makes DataFusion the best technology for a variety of data processing tasks.