You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by ag...@apache.org on 2023/05/04 13:43:35 UTC
[arrow-datafusion-python] branch main updated: First pass of documentation in mdBook (#364)
This is an automated email from the ASF dual-hosted git repository.
agrove pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion-python.git
The following commit(s) were added to refs/heads/main by this push:
new 4175134 First pass of documentation in mdBook (#364)
4175134 is described below
commit 4175134cdf0ed5168282eb88feeb35a7540ac312
Author: Matthew Powers <ma...@gmail.com>
AuthorDate: Thu May 4 10:43:29 2023 -0300
First pass of documentation in mdBook (#364)
* First pass of documentation in mdBook
* Address code review comments
* Add missing ASF headers
---
.gitignore | 4 +-
docs/mdbook/README.md | 33 ++++++
docs/mdbook/book.toml | 23 +++++
docs/mdbook/src/SUMMARY.md | 24 +++++
docs/mdbook/src/images/datafusion-jupyterlab.png | Bin 0 -> 86143 bytes
docs/mdbook/src/index.md | 43 ++++++++
docs/mdbook/src/installation.md | 62 +++++++++++
docs/mdbook/src/quickstart.md | 77 ++++++++++++++
docs/mdbook/src/usage/create-table.md | 59 +++++++++++
docs/mdbook/src/usage/index.md | 25 +++++
docs/mdbook/src/usage/query-table.md | 125 +++++++++++++++++++++++
11 files changed, 474 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore
index 4e44500..1d0a84a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,6 @@ venv
apache-rat-*.jar
*rat.txt
.env
-CHANGELOG.md.bak
\ No newline at end of file
+CHANGELOG.md.bak
+
+docs/mdbook/book
\ No newline at end of file
diff --git a/docs/mdbook/README.md b/docs/mdbook/README.md
new file mode 100644
index 0000000..664b4b4
--- /dev/null
+++ b/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`.
diff --git a/docs/mdbook/book.toml b/docs/mdbook/book.toml
new file mode 100644
index 0000000..089cb9a
--- /dev/null
+++ b/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 <de...@arrow.apache.org>"]
+language = "en"
+multilingual = false
+src = "src"
+title = "DataFusion Book"
diff --git a/docs/mdbook/src/SUMMARY.md b/docs/mdbook/src/SUMMARY.md
new file mode 100644
index 0000000..b490899
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/docs/mdbook/src/images/datafusion-jupyterlab.png b/docs/mdbook/src/images/datafusion-jupyterlab.png
new file mode 100644
index 0000000..c4d4688
Binary files /dev/null and b/docs/mdbook/src/images/datafusion-jupyterlab.png differ
diff --git a/docs/mdbook/src/index.md b/docs/mdbook/src/index.md
new file mode 100644
index 0000000..3cd0fec
--- /dev/null
+++ b/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!
diff --git a/docs/mdbook/src/installation.md b/docs/mdbook/src/installation.md
new file mode 100644
index 0000000..ba00c8b
--- /dev/null
+++ b/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:
+
+
+
+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!
diff --git a/docs/mdbook/src/quickstart.md b/docs/mdbook/src/quickstart.md
new file mode 100644
index 0000000..bba0b36
--- /dev/null
+++ b/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.
diff --git a/docs/mdbook/src/usage/create-table.md b/docs/mdbook/src/usage/create-table.md
new file mode 100644
index 0000000..332863a
--- /dev/null
+++ b/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")
+```
diff --git a/docs/mdbook/src/usage/index.md b/docs/mdbook/src/usage/index.md
new file mode 100644
index 0000000..1ef4406
--- /dev/null
+++ b/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.
diff --git a/docs/mdbook/src/usage/query-table.md b/docs/mdbook/src/usage/query-table.md
new file mode 100644
index 0000000..5e4e380
--- /dev/null
+++ b/docs/mdbook/src/usage/query-table.md
@@ -0,0 +1,125 @@
+<!---
+ 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 Query Table
+
+DataFusion tables can be queried with SQL or with the Python API.
+
+Let's create a small table and show the different types of queries that can be run.
+
+```python
+df = ctx.from_pydict(
+ {
+ "first_name": ["li", "wang", "ron", "amanda"],
+ "age": [25, 75, 68, 18],
+ "country": ["china", "china", "us", "us"],
+ },
+ name="some_people",
+)
+```
+
+Here's the data in the table:
+
+```
++------------+-----+---------+
+| first_name | age | country |
++------------+-----+---------+
+| li | 25 | china |
+| wang | 75 | china |
+| ron | 68 | us |
+| amanda | 18 | us |
++------------+-----+---------+
+```
+
+## DataFusion Filter DataFrame
+
+Here's how to find all individuals that are older than 65 years old in the data with SQL:
+
+```
+ctx.sql("select * from some_people where age > 65")
+
++------------+-----+---------+
+| first_name | age | country |
++------------+-----+---------+
+| wang | 75 | china |
+| ron | 68 | us |
++------------+-----+---------+
+```
+
+Here's how to run the same query with Python:
+
+```python
+df.filter(col("age") > lit(65))
+```
+
+```
++------------+-----+---------+
+| first_name | age | country |
++------------+-----+---------+
+| wang | 75 | china |
+| ron | 68 | us |
++------------+-----+---------+
+```
+
+## DataFusion Select Columns from DataFrame
+
+Here's how to select the `first_name` and `country` columns from the DataFrame with SQL:
+
+```
+ctx.sql("select first_name, country from some_people")
+
+
++------------+---------+
+| first_name | country |
++------------+---------+
+| li | china |
+| wang | china |
+| ron | us |
+| amanda | us |
++------------+---------+
+```
+
+Here's how to run the same query with Python:
+
+```python
+df.select(col("first_name"), col("country"))
+```
+
+```
++------------+---------+
+| first_name | country |
++------------+---------+
+| li | china |
+| wang | china |
+| ron | us |
+| amanda | us |
++------------+---------+
+```
+
+## DataFusion Aggregation Query
+
+Here's how to run a group by aggregation query:
+
+```
+ctx.sql("select country, count(*) as num_people from some_people group by country")
+
++---------+------------+
+| country | num_people |
++---------+------------+
+| china | 2 |
+| us | 2 |
++---------+------------+
+```