Skip to content

Commit

Permalink
Expand README with details of storage use
Browse files Browse the repository at this point in the history
Add a note about defining `method` paramter for the datastore_upsert endpoint.
  • Loading branch information
brew committed Oct 31, 2017
1 parent 657faa6 commit 8d92b7e
Showing 1 changed file with 29 additions and 2 deletions.
31 changes: 29 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ pip install tableschema-ckan-datastore

Code examples in this readme requires Python 3.3+ interpreter. You could see even more example in [examples](https://github.com/frictionlessdata/tableschema-ckan-datastore-py/tree/master/examples) directory.

When writing data, tableschema-ckan-datastore uses the [CKAN API `datastore_upsert` endpoint](https://ckan.readthedocs.io/en/latest/maintaining/datastore.html#ckanext.datastore.logic.action.datastore_upsert) with the `upsert` method. This requires a unique key in the data defined by a [Table Schema primary key property](https://specs.frictionlessdata.io/table-schema/#primary-key). If your data has a primary key, you can use the `table.save` method:

```python
from tableschema import Table

Expand All @@ -34,14 +36,39 @@ base_url = 'https://demo.ckan.org'
dataset_id = 'test-dataset-010203'
api_key = 'my-ckan-user-api-key'

table = Table('data.csv', schema='schema.json')
table = Table('data.csv', schema='schema.json') # data.csv has primary keys
table.save(resource_id,
storage='ckan_datastore',
base_url=base_url,
dataset_id=dataset_id,
api_key=api_key)
```

If you need to define the method used to save data to the DataStore, you can create the `tableschema.Storage` object directly and specify which method parameter to use:

```python
import io
import json
from tabulator import Stream
from tableschema import Storage

# Load and save CKAN DataStore record
resource_id = 'bd79c992-40f0-454a-a0ff-887f84a792fb'
base_url = 'https://demo.ckan.org'
dataset_id = 'test-dataset-010203'
api_key = 'my-ckan-user-api-key'

schema = json.load(io.open('schema.json', encoding='utf-8'))
data = Stream('data.csv', headers=1).open()

storage = Storage.connect('ckan_datastore',
base_url=base_url,
dataset_id=dataset_id,
api_key=api_key)
storage.create(resource_id, schema, force=True))
storage.write(resource_id, data, method='insert') # specify the datastore_upsert method
```

## Documentation

The whole public API of this package is described here and follows semantic versioning rules. Everything outside of this readme are private API and could be changed without any notification on any new version.
Expand Down Expand Up @@ -102,7 +129,7 @@ and `mock` packages. This packages are available only in tox envionments.

## Changelog

Here described only breaking and the most important changes. The full changelog and documentation for all released versions could be found in nicely formatted [commit history](https://github.com/frictionlessdata/tableschema-sql-py/commits/master).
Here described only breaking and the most important changes. The full changelog and documentation for all released versions could be found in nicely formatted [commit history](https://github.com/frictionlessdata/tableschema-ckan-datastore-py/commits/master).

### v0.x

Expand Down

0 comments on commit 8d92b7e

Please sign in to comment.