Cursors

Cursors are created by results that return a set of results. They are accessible as a feature of the session. Using the Options operator, you can see the ways in which a cursor can be created.

OPTIONS http://server:port/geognosis/9/sessions/session_id/cursors.json

TIP: For information on using expressions to create cursors, see Expressions.

Using Cursors

Cursors are usually created as a result of running a number of requests such as ST_Intersect query on overlay 2. They require a POST request:

POST
http://lserver:port/GeognoSIS/9/Sessions/session_id/Cursors.json?source=./Map/Overlays/2&f=ST_Intersects(geometry,ST_GeomFromText("POLYGON((523586 223347,523612 223357,523616 223343,523598 223333,523586 223347))","EPSG:27700"))

You can then access the first 10 items in the cursor using this request:

GET http://server:port/GeognoSIS/9/Sessions/Cursors/4W9d3AjzakuaeV4AD2CoXw.json?n=10

To get the next 10 items, you can use:

GET http://server:port/GeognoSIS/9/Sessions/Cursors
/4W9d3AjzakuaeV4AD2CoXw.json?n=10&start =11

or use “Next” part of the response:

GET http://server:port/GeognoSIS/9/
Sessions/Cursors/4W9d3AjzakuaeV4AD2CoXw.json?n=10&next=R38450370

To determine if the end of the cursor has been reached, check the “Next” parameter exists.

Cursor Performance and Life Cycle

For performance reasons, each “Next” parameter can only be used once. Once you’ve reached the end of the cursor, it is useless.

To start over, simply create a new cursor.

It is good practice to delete cursors when you have finished with them. You can do this using a DELETE request.

DELETE http://server:port/GeognoSIS/9/Sessions/Cursors/4W9d3AjzakuaeV4AD2CoXw.json

Alternatives to Cursors

You don’t have to store your results in a cursor; if you reference the overlay directly and add an upper limit for the number of features you want returned (in this case 2000), these can be held as items on the overlay. This technique only requires a GET request:
GET http://local host:portnumber/geognosis/9/sessions/d26a54f1-6773-4dcb-8238-1cb9b93a0ecc/map/overlays/1/Items.json?f=ST_Intersects(geometry,ST_GeomFromText("POLYGON((523586 223347,523612 223357,523616 223343,523598 223333,0 0))","EPSG:27700"))&n=2000

This request will return the items found by the ST_Intersect query, which can then be stored locally. The items can also be accessed directly as required using:

Items.json?start=0&n=10
Items.json?start=10&n=10
Items.json?start=20&n=10

This technique can be quicker than using a cursor for larger datasets (over 50 items) and does not require a POST request.

For performance reasons, the state is cached by default for around 30 seconds to provide fast access to these results. The cache timeout can be configured with the request using the parameter “cachehint” in the following way:

  • cachehint=60000 means 60 seconds timeout
  • cachehint=INFINITE means the state lives as long as the session
  • cachehint=NO-CACHE means the state isn’t cached at all
GET http://localhost:portnumber/geognosis/9/sessions/d26a54f1-6773-4dcb-8238-1cb9b93a0ecc/
map/overlays/1/Items.json?f=ST_Intersects(geometry,ST_GeomFromText(
"POLYGON((523586 223347,523612 223357,523616 223343,523598 223333,0 0))","EPSG:27700"))&n=2000&cachehint=60000