wiki:Developer/DataServer
DatabaseCore
============

The original discussion for the interface  is in DataServer



Database objects are access through the web service Data Service.  This web service is RESTful in it's interface and deals with XML documents.

Basic object types in Bisquik:

#. Image   : An image including it's src and dimensions
#. Tag     : A labeled data item
#. GObject : A graphical objects relative to the image.
#. Dataset : a group of objects



Operations
===========

Objects are created by HTTP posting to the Dataservice.   In order to use these services, in many cases
you will need authorization.  This is discussed in BisquikAuthorization.

#. POST  create/append a resource 
#. DELETE   delete a resource
#. GET   fetch a resource  
#. PUT   replace a resource 

It is sometimes best to lead with an example.  Below we show how to create a new image object::

  POST /data_service/image
    <image name="my image" value="http://image.com/new.jpg"  />
  ==>
     <image uri="http://host/data_service/images/12" value="http://image.com/new.jpg" name="my image" />


Note that a uri is added to the image representing the id of Image to be used in later operations.  Also note
that the {{{value}}} address did not change.  ''Image are not actually stored by data service''.  If image storage is
required, then the image service can be used.


Creating tags on images is easy::

  POST /data_service/image/12
  <image uri='/data_service/image/12' >
    <tag name="comment" value="This is a comment" />
    <tag name="name"    value="new" />
  <//image>
  ==>
     <image uri="http://datahost/ds/images/12" src="http://image.com/new.jpg" x="512" y="512" z="1" t="1" ch="3" />



Datasets are a little different::


  POST /data_service/dataset
    <dataset  name="Experiment 1" >
        <value type="object">http://datahost/ds/images/12</value>
    </dataset>
  ==>
     <dataset uri="http://datahost/ds/datasets/40" name="Experiment 1" >
          <value index="0" type="object">http://datahost/ds/images/12</value>
    </dataset>


You can directly address the elements of the dataset as follows::

   GET /data_service/dataset/40/tags/44/values 
  ==>
   <resource uri='/data_service/dataset/40/tags/44/values'
     <value index="0" type="object">http://datahost/ds/images/12</value>
   </resource>

Replace elements::
   
   PUT /ds/datasets/40/tags/44/values 
  <resource>
        <value type="object">http://datahost/ds/images/12</value>
        <value type="object">http://datahost/ds/images/12</value>
        <value type="object">http://datahost/ds/images/12</value>
  </resource>
  ==>
   <response></response>



Other types available::

   /ds/image     : parameters view=[count, full, deep] limit=#, offset=#, tag_query="some tags" 
   /ds/tag      :
   /ds/gobject
   /ds/dataset

Standard query parameters
=========================

view
  Change the output format of the returned resource [short, full, deep], clean, 
limit
  Limit the number of items returned
offset 
  used with limit to fetch more items 
tag_query
  see below.
tag_order
  Order the response based on the values of a tag
format
  set the format of the response xml, csv, etc.
resource attributes 
   Resource attributes (name,value,type, hidden, ts, created) can be queried including the use of relational operators::

        /image?name=10.stk
        /image?ts<2010-10-01T12:00:00&ts>=2011-10-01T12:00:00

Tag Query Operations
====================


   #.  Query resources (image) by underlying tag::

       /image?tag_query=[TYPE:[[NAME:]VAL...&]]

   #.  return values list of all experimenters in the above query::
       
       /image?tag_query=[TYPE:[[NAME:]VAL...&]tag_values=experimenter

   #. return values list of all available tag names on query::

       /image?tag_query=[[TAG:]VAL...&]tag_names=1

   #. Combination of value or tag names::
 
       /image?tag_query="tag1:value1 [and|or] value2"

Tag Special Operations
=======================
    
   #.  Return all tha available tag names for the given superquery::

       /image/?tag_names=1

   #.  all possible values for a particular tag name::

       /image?tag_values=tag_name

   #. all tags have a name="tag_name" as an attribute::

       /tag/?name=tag_name   : 

   #. all tags having a value attribute of tag_val::

       /tag/?value=tag_val   : 

   #. Extract lots info (names of tags, value of tags with name qq, and types of gobjects 

      /image/?extract=tag[name],tag[value, name="qqq"],gobject[type]

      The syntax is   ?extract=<expr> ::

       <expr> := resource_type [ <attribute>', <filter>,... ] 
       <attribute> := name, value, type
       <filter>  := <attribute> <relop> <literal>
       <relop>   := '='
       <literal>  is a trsint


 
Tag order operations
====================

 Tag order specifies the sort order of the returned items.  

  #. return images sorted by time stamp(most recent first)::

       /image?tag_order=@ts:desc

  #. sorted by a particular tag value::

       /image?tag_order=tagname:asc

/data_service/ ::

Return a list of available resources at this root. An example return would be

<resource> 
  <resource uri="http://loup.ece.ucsb.edu:9090/data_service/image" name="image"/>
</resource>

Each resource returned would be queryable:

/data_service/image ::

Return a list of images available at the site

<resource>
  <image resource="/images/1" />
 ...
</resource>

Data services are available for all predefined object types:

/image
/tag
/gobject
/template
/module
/dataset

Template::

Return a list of tags representing the names and defualt values

Tag::

All tags in the database (should be limited to user)

gobject::

Same as above

module::

List of registered modules

<module name="m1" resource="/module/1/" engine="matlab">
  <tag name="formal-input" value="resource image" />
  <tag name="formal-output" value="resource image" />
</module>

dataset::

A set of values or resource references

User objects

Templates define user groups of objects i.e. groups of tags. A template can be instantiated on

an object (tags are added to current object) or as a separate addressable resource:

Creating a user object

Post a document to a template resource will create a user object.

i.e. If the system has defined the 'microtubule' template then access to instances is available under /microtubule, and

posting the following XML document to /microtuble/

will result in the creation of a new microtubule resource.

  <resource resource_type="microtubule"> 
    <tag name="name" value="mt1" />
    <tag name="cell_type" value="hela" />
    <tag name="track" >
        <gobject type="mt_track">
            <point x="100" y="100" t="0" >
        </gobject>
  </resource>

The result of the post will be the create resource

   <resource resource_type="microtubule" uri="/microtubule/1" />

Retrieving a user object

Example. A microtubule template consists of several tags:

name string cell_type string track resource (gobject)

  /microtubule/1/
  <resource resource_type="microtubule">
    <tag name="name" value="mt1" />
    <tag name="cell_type" value="hela" />
    <tag name="track" value="/gobject/2" />
  </resource>

Last modified 3 years ago Last modified on 10/20/2016 04:43:19 PM