This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Quickstart
==========
Hi, welcome to the twelve-minute quick-start tutorial.
Connecting to a database
------------------------
At first you need to import the dataset package :) ::
import dataset
To connect to a database you need to identify it by its `URL <http://docs.sqlalchemy.org/en/latest/core/engines.html#engine-creation-api>`_, which basically is a string of the form ``"dialect://user:password@host/dbname"``. Here are a few common examples::
# connecting to a SQLite database
db = dataset.connect('sqlite:///mydatabase.db')
# connecting to a MySQL database with user and password
db = dataset.connect('mysql://user:password@localhost/mydatabase')
# connecting to a PostgreSQL database
db = dataset.connect('postgresql://scott:tiger@localhost:5432/mydatabase')
Storing data
------------
To store some data you need to get a reference to a table. You don't need to worry about whether the table already exists or not, since dataset will create it automatically::
# get a reference to the table 'person'
table = db['person']
Now storing data in a table is a matter of a single function call. Just pass a `dict`_ to *insert*. Note that you don't need to create the columns *name* and *age*– dataset will do this automatically::
# Insert a new record.
table.insert(dict(name='John Doe', age=46))
# dataset will create "missing" columns any time you insert a dict with an unknown key
Using ``len()`` we can get the total number of rows in a table:
>>> print len(db['user'])
187
Reading data from tables
------------------------
Now let's get some real data out of the table::
users = db['user'].all()
Searching for specific entries::
# All users from China
users = table.find(country='China')
# Get a specific user
john = table.find_one(email='john.doe@example.org')
Using :py:meth:`distinct() <dataset.Table.distinct>` we can grab a set of rows with unique values in one or more columns::
# Get one user per country
db['user'].distinct('country')
Running custom SQL queries
--------------------------
Of course the main reason you're using a database is that you want to use the full power of SQL queries. Here's how you run them with ``dataset``::
result = db.query('SELECT country, COUNT(*) c FROM user GROUP BY country')
for row in result:
print row['country'], row['c']
Exporting your data
-------------------
While playing around with your database in Python is a nice thing, sometimes we want to use our data –or parts of it– elsewhere, say in a interactive web application. Therefor ``dataset`` supports serializing rows of data into static files such as JSON using the :py:meth:`freeze() <dataset.freeze>` function::
# export all users into a single JSON
result = db['users'].all()
dataset.freeze(result, 'users.json')
You can create one file per row by setting ``mode`` to "item"::
# export one JSON file per user
dataset.freeze(result, 'users/{{ id }}.json', mode='item')
Since this is a common operation we made it available via command line utility ``datafreeze``. Read more about the `freezefile markup <https://github.com/spiegelonline/datafreeze#example-freezefileyaml>`_.