Model API

List all members

A List of all collection Member instances can be retrieved from the database with the list() method:

List<Member> everybody = persons.list()
everybody.each { person ->
    println person.firstname
}

List a subset of members

A List of the subset of Member objects can be retrieved by passing a filtering condition to the list method as an argument (see Filter Conditions section below for further details):

List<Member> somePersons = persons.list(firstname__startswith: 'Jo')
somePersons.each { person ->
    println person.birthdate
}

Create a new member

A new Member instance can be created and saved into the backing database with the create(Member) method:

Member member = new Member(firstname:'Joe', birthdate:'1978-01-21', ischild: true)
Member person = persons.create(member)

A shortcut is provided to simply send in a Map:

Member person = persons.create(firstname:'Joe', birthdate:'1978-01-21', ischild: true)

Retrieve a member

An individual collection member can be retrieved from the database with the retrieve(Object) method:

Member person = persons.retrieve(1)

Update a member

A collection member can be updated in the database with the update(Map) method:

Member member = new Member(id: '1', firstname:'Bob', birth_date:'1961-12-05')
Member result = persons.update(member)

Similar to the overloaded create() methods, update() has a convenience method for Maps:

Member result = persons.update(id: '1', firstname:'Bob', birth_date:'1961-12-05')

Delete a member

A collection member can be deleted with the delete(Object) method:

boolean result = persons.delete(1)

The delete() method returns true if the delete operation was successful, otherwise it will return false.

Filtering and excluding members

A filter or exclusion can be applied to a collection to create a new collection that is a subset of the original. Each filtered collection is a distinct collection instance that can be stored, used, and reused independent of its parent. The filter conditions can be passed in dynamically, which eliminates the need for writing a different service for each subset of the data that the client might need. The filters can be chained, therefore each filter creates a new logical subset-collection. However, data is not retrieved from the database until a collection member is actually accessed.

def somePersons = persons.filter(firstname__startswith: 'Jo')
def fewerPersons = somePersons.filter(firstname__endswith: 'e')
....or....
def fewerPersons = persons.filter(firstname__startswith: 'Jo').filter(firstname__endswith: 'e')

def birthdate_not_christmas = persons.exclude(birthdate__month: 12, birthdate__day: 25)

def filtered_and_excluded = persons.filter(ischild: true).exclude(firstname__in: ['Phil', 'Brian'])

Filter conditions

The filter conditions are specified using the following convention: [field name][delimiter][operator]. This convention makes the Model API and HTTP API symmetric (this convention makes it easy to pass filters as URI parameters). The supported filters are:

More than one filter condition can be combined with logical AND using a comma as a separator between the filters:

def somePersons = persons.filter(firstname__startswith: 'Jo', birthdate__before: '1990-12-12')

Paging collections

Often it is impractical and inefficient to return the full results of a collection, the Model API supports a paging scheme you can use to indicate what slice of data a list() or filter() call should return.

def paged_people = collection[10..19].list()

def filtered_paged = collection.filter(firstname__endswith: 'ph')[200..299].list()

def filtered_paged = collection.filter(firstname__endswith: 'ph').limit(201,100).list()

in()

The in() method takes a list of identifiers and returns a map where the key is the id of the Member and the value is the Member itself. This is useful when you have a small set of Members to operate on:

def subset = collection.in([30, 10, 32021])
def member30 = subset[30]
def member32021 = subset[32021]

orderBy()

The orderBy() method returns a new Collection instance with the orderBy attribute of the new Collection set to the parameter of the method. The method takes a list of strings and is provided to be used in the method chaining abilities of filter() and exclude(), and paging:

// SELECT * FROM persons ORDER BY birthdate DESC
def youngest_to_oldest = collection.orderBy(['-birthdate']).list()
// SELECT * FROM persons WHERE firstname LIKE '%don' ORDER BY updated
def filtered = collection.exclude(firstname__endswith: 'don').orderBy(['updated']).list()

The orderBy() method supports ordering that is both ascending and descending. The example above illustrates both usages. If the field is prepended with "-" than this indicates that the order is to be descending as used with ['-birthdate']. Ascending should not have a "-" as in ['updated'].

You should note that orderBy() takes a list of strings that are field names. Thus you can order by multiple fields using both ascending and descending. For instance, the following example specifies three fields and the equivalend SQL:

// SELECT * FROM persons WHERE firstname LIKE '%don' ORDER BY updated, firstname, birthdate DESC
def filtered = collection.orderBy(['updated', 'firstname', '-birthdate']).list()

latest()

The latest() method returns the most recently updated Member of the Collection instance. This method can be used with filter() and exclude() methods in order to refine the Collection first:

def latest = collection.latest()
def filtered_latest = collection.filter(birthdate__year: '1978').latest()

The latest() method is simply a shortcut for setting the orderBy attribute of the Collection instance, limiting the fetched size to 1 and returning the first result.

iterator()

Collection implements the Java™ Iterable interface and returns an Iterator of its Members:

def persons = TypeCollection.retrieve('persons')
persons.each { member ->
   println member.firstname
}

size()

The size() method will return the total matched size. If the Collection is unfiltered, the size is the total number of Members in the Collection. Calling this method has the side affect of evaluating the Collection if it has not yet been. The size is cached so subsequent calls to this method do not require accessing the database again:

def persons = TypeCollection.retrieve('persons')
def numberOfPeople = persons.size()

def numberOfSomePeople = persons.filter([first_name__startswith: 'B']).size()

Remember, size() is a method on Collection and can be chained with any method that returns a Collection as shown above with filter().

Named collections

Filters can be specified in the model declaration by defining a named collection:

{
    "fields" : { . . . },

    "collections" : {
        "children": {"memberFilters": {"ischild": true}}
    }
}

In Groovy, a named collection is accessed in the following way:

def persons = TypeCollection.retrieve('persons')
def children = persons.children.list()
def childrenNamedBob = persons.children.[0..4].list(firstname: 'Bob')