Queries

NOTE: Queries are only available in the Diary++ version.

Overview

JXCirrusDiary is a big database that contains a whole lot of time information. And what would a database be without the ability to run queries on it. So in true DB spirit, JXCirrusDiary provides query functionality.

The queries are defined in the database schema. If you are lucky enough to have had someone else create a couple of queries, you can just run them (see Running Queries) and even export them (see Exporting Queries).

If you want to create your own queries, you will need clamp your nerd hat firmly on your head. It would also help to read up a bit about the Database Schema - It will tell you a whole lot that you need to know about Object Specs and Variables.

Running Queries

Running queries is pretty simple. Just select the Query menu and pick the query that you want (for mobile apps, this is under the Menu button).

After it has run, a new tab will be opened with the results of the query displayed like a spreadsheet.

If you don't want that tab open any more, just select the tab (so you can see the query results) and then select View -> Close Tab (or Close on the toolbar).

If you have made some changes to the diary since you ran the query, you don't need to close the query and re-run it. Just click on the query tab, and select View -> Refresh and the query will be re-run. Pressing F5 does the same thing...

The query results will be sorted in ASCII order on the first column (the same as text fields in Excel). If you want to sort on a different column, just click on the column header and the results will be re-sorted.

Clicking on any row will cause that entry to be selected in the rest of the diary.

Exporting Queries

Once you have run a query, you can export the results to a file. To do this, click on the query tab, and select File -> Export -> Query. You will then be prompted to enter a file name. Type the name of the file that you want to save (and also pick its location), then press save. Done!   NOTE: iOS will not let you write out files, sadly!

The queries are saved out as a CSV file (which stands for Comma Separated Values). This is a very basic but faintly handy format... You can load it into all sorts of other applications, like Microsoft Excel, Microsoft Access, Vim, Ed...

What the Query Gives You

Queries return a table of results with:

Fields define the actual data from the database.

Entries are records in the database that match a set of conditions for the query.

Fields

A field is a column that appears in the results table. These columns can contain actual records from the matching entries, or values calculated by the system.

A field definition looks like this:

Field: Title=TITLE, Value=VALUE, From=TABLE, [TAG=VALUE];

Fields have 3 mandatory parts.

  1. Title - This is what will appear in the column header in the table. It can be any piece of text.
  2. Value - This is the name of a variable attached to the entry or a calculated value from the system. When we talk about Variables, we mean the Variables in Object Specs. Calculated values refer to some special values that the system can add to queries. The calculated values that are available are listed later in this page.
  3. From - Defines the table that the record comes from. In most cases this is "E" (which stands for Entries, or Diary Entries). If the values are a combination of 2 tables, the field will be in the form From=TABLE1+TABLE2 (for example From=E+R. where R stands for Resources, or people).

If field values contain more than one word, then they should be surrounded by quotes, for example:

Field: Title="First Name", Value=First_Name, From=E;

This field will show the value $<First_Name> as defined in your object spec.

Some field definitions can create several columns based on a range. The most common one of these is date ranges. The following defines a date range:

Field: Title="%m-%y", Value=ProjectPlannedPerResource, From=E+R,

RangeType=Date,

RangeStart="now 2AM",

RangeEnd="now 2AM +5 months",

TimeUnits=Hours,

RangeDiv="1 month";

The RangeType indicates that this is a date range. RangeStart tells which date to start at (this can be based on "now" or an actual date. RangeEnd says when the range ends. RangeDiv indicates the amount of time for each column. Field ranges are only available with the System Values listed below.

This query might produce the following:


Apr-11 May-11 Jun-11 Jul-11
65 5 16

62 3 16 14
60 2


Conditions

Conditions define which entries will appear in the results table.

Conditions have the general form:

Condition: CONDITION, Value=VALUE, From=TABLE, [TAG=VALUE];

There are 3 mandatory fields:

  1. CONDITION = This will either compare the text or number values from VALUE with a fixed value.
  2. VALUE = The value to extract from the database to use in the condtion.
  3. TABLE = The table to get the entry from (this is usually "E").

Conditions have one of the forms:

It is possible to use a match against ALL fields in an object. To use this define Value="*". This is useful in combination with Regex conditions to search data. For example:

Condition: Regex=".*Melbourne.*", Value="*", From=E;

looks for any objects containing the word Melbourne in any field.

Prompts

To make queries a bit more re-usable, it is possible to prompt users to enter values that can be used for the query.

Prompt: Title=Name, Value=Geoff;

This will pop up a form that will display the field "Name" with a default value of "Geoff" (the default does not have to be supplied).

This is how the prompt gets used:

Condition: Regex=".*$<Name>.*", Value="*", From=E;

Prompt: Title=Name;

This will search all fields for a match against name.

System Values

Most query fields use the variables from the object specs that you are querying. JXCirrus Diary provides some extra values from the system which are based on data from the entries, but not actual variables. This defines some of the system values that can be queried. These can be used in both Fields and Conditions.

These system values take a number of qualifiers, which change how they are presented.

They also need to know which tables (or data types) they come from. The choices that you have for this are:

Depending on the value you are getting back, you must use the correct value for "From Tables". They are listed next to each of the values.

Anyway, this is horribly hard to explain, and so it is much easier with an example...

An example...

This query will show the amount of planned time for each project for each person. This is a condition for greater than 0.1 days planned during the next 18 months.

Condition: GreaterThan=0.1, Value=ProjectPlannedPerResource, From=E+R,

End="now 1st 2AM +18 months",

Start="now 1st 2AM";

This displays the results of this as a breakdown for the next 18 months.

Field: Title="%b-%y", Value=ProjectPlannedPerResource, From=E+R,

RangeType=Date,

RangeStart="now 1st 2AM",

RangeDiv="1 month";,

RangeEnd="now 1st 2AM +18 months";

The values...


Value Description From Tables Qualifiers
ProjectSpent The amount of time spent working on a each task entry. E TimeUnits, WorkHours, Start, End
ProjectRemaining The amount of time remaining for a task. E TimeUnits, WorkHours
ProjectDuration The total duration of a task. E TimeUnits, WorkHours
ProjectActivityPerResource The amount of time spent + the amount of time planned for each task per person. E+R TimeUnits, WorkHours, Start, End
ProjectSpentPerResource The amount of time spent for each task per person. E+R TimeUnits, WorkHours, Start, End
ProjectPlannedPerResource The amount of time planned for each task per person. E+R TimeUnits, WorkHours, Start, End
ProjectStart
The start date of the task/project.
E

ProjectEnd
The end date of the task/project.
E

ProjectDue
The calculated due date of the task/project (takes dependencies into account)
E

ProjectMustStart
The date that a task must start by.
E

ProjectIdealStart
The date that a task should start by in order for everything to finish on time.
E

ResourceLeave The amount of time a person is on leave. R TimeUnits, WorkHours, Start, End
ResourceFreeTime The amount of unallocated time for a person. R TimeUnits, WorkHours, Start, End
ResourcePlannedTime The amount of planned time for a person. R TimeUnits, WorkHours, Start, End
ResourceWorkHours
The number of work hours available that day.
R
TimeUnits, WorkHours, Start, End

Query Examples

Let us imagine that we have an Object Spec that defines a person (say in an addressbook). It might look like this:

$<FirstName> = prompt();

$<LastName> = prompt();

$<FullName> = eval("$<FirstName> $<LastName>");

$<Phone> = prompt();

$<Address> = prompt();

We could display an addressbook table for them like this...

Field: Title="Last Name", Value=LastName, From=E;

Field: Title = "First Name", Value=FirstName, From=E;

Field: Title = "Phone Number", Value=Phone, From=E;

Condition: Spec=Person, From=E;Field: Title = "Address", Value=Address, From=E;

Let us imagine that we have a Project spec that defines details of a project... It could be broken down into any number of sub-tasks.

This is a query that displays the time spent and the time planned for each person.

# The first column will be the name of the person.

Field: Title=Person, Value=Resource, From=R;

# The second column will be the name of the project.

Field: Title=Project, Value=Project, From=E;

# The third (and onwards) columns will be the number of hours

# to be worked or already worked on that project per month.

# - The title will be "Month-Year" (see C-style date formats).

# - The value it reports is ProjectActivityPerResource

# - The data comes from a combination of project Entries (the

# actual projects), and Resources (the people).

# - We are breaking this down into a date rabnge.

# - We will report in hours.

# - We start 12 months ago.

# - We finish in 12 months time.

# - We break down the time by months.

Field: Title="%b-%y", Value=ProjectActivityPerResource, From=E+R,

RangeType=Date,

RangeStart="now 1st 2AM +-12 months",

RangeEnd="now 1st 2AM +12 months",

TimeUnits=Hours,

RangeDiv="1 month";

# We will only report on specs of type Project.

Condition: Spec=Project, From=E;

# The person must have worked more than 0.5 hours on that project

# during the reporting period.

Condition: GreaterThan=0.5, Value=ProjectActivityPerResource,

From=E+R,

TimeUnits=Hours,

End="now 1st 2AM +12 months";Start="now 1st 2AM +-12 months",

If we wanted to display the amount of unused time for each person on our staff (from the JXCirrus Project samples).

# The first column will be the name of the person.

Field: Title=Person, Value=Resource, From=R;

# The second (and onwards) columns will be the number of hours

# that the person could be working, but are not assigned to any

# work.

# - The title will be "Month-Year" (see C-style date formats).

# - The value it reports is ResourceFreeTime

# - The data comes the Resource table only.

# - We are breaking this down into a date rabnge.

# - We start this month.

# - We finish in 12 months time.

# - We break down the time by months.

Field: Title="%b-%y", Value=ResourceFreeTime, From=R,

RangeType=Date,

RangeStart="now 1st 2AM",

RangeEnd="now 1st 2AM +24 months",

RangeDiv="1 month";

# This makes sure the person is actually working during that time

# period (otherwise, you would end up reporting on people who have

# left the company).

Condition: GreaterThan=0.1, Value=ResourcePlannedTime, From=R,

Start="now 1st 2AM",

End="now 1st 2AM +24 months";

# This only reports on people who have more than 0.1 days of free

# time during the period.

Condition: GreaterThan=0.1, Value=ResourceFreeTime, From=R,

Start="now 1st 2AM",

End="now 1st 2AM +24 months";