Hi, in this blog I will describe the basics of searching for articles and connections. Appacitive keeps your data indexed and cached so as to provide real-time searching and mining.
Articles/Connection Searches -
Articles are instances of schemas and hold values in their properties, properties which are described by their parent schemas. Conversely, connections are instances of relations and also hold property values as specified in their parent relations. For example, in a social network model, a schema could be Persons and articles for schema Persons would be you and me. We would have properties to describe us like name, gender, display picture, favourites, hobbies, last checkin, date of birth etc. And there could be a relation called friends with the schema Person on both ends depicting a friend relationship between two persons.
Other schemas could be other objects in the system like songs, movies or recipes. You could have a connection with a movie which would have properties like the date you watched the movie and the rating you gave it. You could also have a connection with a song describing when you heard it and what rating you gave it. Here is the model we will use in this tutorial to understand the search API(s).
Now consider you have this model and have lots of people signed in and also have a considerable amount of data. Now coming to searching for articles/connections for your application. First come the filter queries.
Query filters are passed in the URL as Query String Parameters. Search calls are HTTP GET calls with two headers, Appacitive-Session and Appacitive-Environment.
These searches are the same for both articles and connections.
I. The basic search -
Now if you wanted a paginated list of all the movies (all articles of schema movies) in the system ordered by their release date,
II. The filter search -
Additional filters are applied by passing a filter query on `properties`, `attributes` and `aggregates` in a query string parameter called `query`.
Property names are prefixed with ‘*’.
Attribute names are prefixed with ‘@’.
Aggregate names are prefixed with ‘$’.
If you wanted all love stories before 1970
GET http://apis.appacitive.com/Article/movies/find/all?query=*genre == ‘love story’ and *release_date < date(’1970-12-12′)
If you want all movies which contains the word ‘love’ in its name and attribute with key ‘opening’ and value ‘blockbuster’.
GET http://apis.appacitive.com/Article/movies/find/all?query=*name like ‘*love*’ and @opening == ‘blockbuster’
This way you can create your desired query using and/or and >,<,==,<= and >=.
Date, time and datetime values need to be cast into types they are being compared with like date(’1970-12-12′) or datetime(’1964-12-11T00:00:00.0000000′)
III. The free-text search
As all your data is indexed you can fire free-text queries on any textual property in your model.
If you wanted all songs with the words ‘rock’ and ‘roll’ in their lyrics
GET http://apis.appacitive.com/Article/songs/find/all?freetext=rock roll&language=english
IV. The tags search
As all articles (and connections) contain tags, which are also kept indexed in memory, you can fire queries on tags along with other parameters. There are two kinds of queries on tags.
a. Tagged with one or more – returns articles which have at least one of the specified tags.
GET http://apis.appacitive.com/Article/songs/find/all?properties=tagged_with_one_or_more (‘rock pop trance’)
b. Tagged with all – returns articles tagged with all the specified tags.
GET http://apis.appacitive.com/Article/songs/find/all?properties=tagged_with_all (‘rock 1969 woodstock’)
V. The between search
You can provide min and max range values and retrieve values which fall between them. Such between searches can be fired on numeric (long,decimal) and chronological properties (date,time and datetime).
For example if you wanted to retrieve all music albums from the 1960′s which cost between $5 and $15.
GET http://apis.appacitive.com/Article/songs/find/all?properties=*release_date between (date(’1960-01-01′) date(’1970-12-12′) ) and *price between (5 15)
VI. The geographical search
Appacitive understands geo coordinates in the form of a longitude and latitude which can be used to perform spatial searches of two types.
a. Radial search – For when you are hunting for articles around you with you as the centre and a predetermined radius.
Say you are at (10.10,20.20) and are looking for articles (other users) in a 100 mile radius.
GET http://apis.appacitive.com/Article/persons/find/all?properties=(*current_location within_circle 10.10,20.20,100 mi)
Possible metrics for radial distance are ‘mi’ or ‘miles’ for miles and ‘km’ for kilometer.
b. Polygon search – When you are hunting for articles inside a ploygon. You need to provide the coordinates of three vertices. Say the three vertices are (0,0), (10,0), (0,10).
GET http://apis.appacitive.com/Article/persons/find/all?properties=(*current_location within_polygon 0,0 | 10,0 | 0,10)
These are the possible searches that can be performed on articles and connections.
Important : Additionally you can mention in your query (or any GET call) exactly which all fields you want returned so as to reduce payload. The query string parameter is `fields`.
This was the basic querying DSL. The next tutorial will aim to explain the more advanced searching techniques.