/tiny-NoSQL

A Python implementation of NoSQL database

Primary LanguagePython

tiny NoSQL

A tiny implementation of NoSQL database with RESTful API support.

Install

Getting Started

Python Interface

from nosql import Database

Database

  • Create a database: db = Database('./YOUR_DATABASE_DIRECTORY/')
  • Show collections in database: db.show_collections()
  • Create a new collection: db.create_collection(NEW_NAME)
  • Get the collection object from a database: col = db.get_collection(NAME)
    • Alternatively, you can also call a collection as an attribute. For example, db.main will return the collection with name main.
  • Delete a collection from a database: db.drop_collection(NAME)
  • Close and save database: db.close()

Collection

  • Return all documents from collection: col.all()
  • CRUD Operations: Please see CRUD section

RESTful API

Start the nosql.py with corresponding argument. By default the database will run on localhost:9020, and the examples below are based on this.

CRUD Operations

Suppose there exists a collection named fruits.

Insert New Documents

Pythoncol.insert({'type':'banana', 'price': 10})
RESTful curl -X "POST" "http://localhost:9020/fruits/_insert?type=banana&price=10"
RESTful JSON

curl -X "POST" "http://localhost:9020/fruits/_insert" \
     -H 'Content-Type: application/json' \
     -d $'{
  "type": "banana",
  "price": 10
}'

Supported document types: a JSON object or Python dictionary is acceptable. The valid types include float, integer, string and nested array or object.

Find all

To retrieve all documents in a collection.

Pythoncol.all()
RESTful curl "http://localhost:9020/fruits/_all"

Find with document ID

A UUID-format document ID will be generated every time a document is inserted. The document ID will be returned after the insertion.

Pythoncol.find({'_id': DOC_ID})
RESTful curl "http://localhost:9020/fruits/DOC_ID"
RESTful JSON

curl "http://localhost:9020/fruits/_find" \
     -H 'Content-Type: application/json' \
     -d $'{
  "_id": "DOC_ID"
}'

Find with criterion

Pythoncol.find({'type': 'banana'})
RESTful curl "http://localhost:9020/fruits/_find?type=banana"
RESTful JSON
curl "http://localhost:9020/fruits/_find" 
     -H 'Content-Type: application/json' 
     -d $'{
  "type": "banana"
}'

Supported query criteria

The query criteria must be a query string, JSON object, or Python dictionary. Below are examples of JSON object criteria.

  • _id: UUID string. Specify document id to find the exact document.
  • Equal: Use field/value pair to find all documents with field matching the value.
  • Contain: Use field/value pair to find all documents with lists containing the value.
    • e.g. {"type": "orange", "taste": ["sweet", "sour"]} will be matched with criterion {"taste": "sweet"}
  • Advanced search
    • _eq: equal. E.g. {"_eq": {"taste": "sour"}} will only match documents with taste equal to sour.
    • _lt, _le: less than, less or equal to.
    • _gt, _ge: greater than, greater or equal to.
    • _ne: not equal to.
    • _in: is in.
    • _nin: is not in.

Update with criterion

For example, if you want to add 1 dollars to all products with price lower than 10 dollars, this contains a query (find all documents with price <10), and an update operation (increase price by 1 ). The JSON needs to contain to object: "criteria" and "operation".

Pythoncol.update({"price":{"_lt":100}}, {"_increment": ["price"]})
RESTful JSON

curl -X "PUT" "http://localhost:9020/fruits/_update" \
     -H 'Content-Type: application/json' \
     -d $'{
  "operation": {
    "_increment": [
      "price"
    ]
  },
  "criteria": {
    "price": {
      "_lt": 10
    }
  }
}'
It will return a list of document id of all documents updated. You can also update a sepecific document by using document id as the criteria.

Supported Update Operations

  • _set: key/value paris of fields to update and new values
  • _unset: list of fields to be deleted
  • _increment: list of fields to increase by one. Need to be numeric values.
  • _append: key/value paris of fields and values to be appended

Remove documents

Pythoncol.remove({'type': 'banana'})
RESTful curl -X "DELETE" "http://localhost:9020/fruits/_remove?type=banana"
RESTful JSON
curl -X "DELETE" "http://localhost:9020/fruits/_remove" \
     -H 'Content-Type: application/json' \
     -d $'{
  "operation": {
    "_increment": [
      "price"
    ]
  },
  "criteria": {
    "price": {
      "_lt": 100
    }
  }
}'