Querki Quickstart

Welcome to Querki!
This page is a super-fast introduction to the basic concepts of Querki. It is not in any way a tutorial, and is aimed at experienced current programmers. If you'd like a gentler introduction, I recommend reading Learning Querki. But here's the ten-minute introduction, which should be enough to get started.
Personal introduction: I'm Justin -- the CEO and Architect for Querki. Glad to have you here!

What is Querki?

Basically, it is an cloud-based application platform: a hybrid between an object-oriented database, a super-concise programming language and a lot of wiki look-and-feel.
The central idea is that we all have little collections of data that aren't huge and complex, and aren't worth building a whole formal database and website. We mostly wind up using spreadsheets, documents, and even paper to track them -- but they are still databases, and less-structured approaches gradually get in the way.
Querki is aimed squarely at this problem: the many small databases that people and small businesses have to manage every day. It is designed for messy, evolving, real-world data that you are trying to keep organized. Most importantly, it is designed to get out of your way as much as possible, making it quick and easy to set up and change your data structures, so you can mostly just focus on using data.
It is also fundamentally online and collaborative. Most interesting problems involve more than one person: for most of them you'd really like to be able to control access, have discussions about the data, and generally work together. And it is increasingly mobile-focused: it is designed to work decently on mobile devices from the outset, and we're gradually making that experience smoother and more powerful.
All of this is built-in, allowing you to set up a new Space in minutes, with the data structures, security, collaboration and look-and-feel you want.
Putting it a bit more simply: Querki is a software platform for the Maker age -- trying to make the process of building a space easy enough for everyone to do, not just professional programmers.
As of this writing, Querki is in open Beta: the core elements are in place, and you can build useful stuff in it. I encourage you to sign up, start playing around, and ask questions on the development journal. Lots more is yet to come, and I have plans to make it better and better over the next few years. But it's good enough for many of the simpler use cases now.

Main Concepts

Most of the high-level concepts in Querki should be familiar to an experienced programmer. But all of it has been rethought, and it is all aimed at normal end users, so a lot of the terminology is unique to the system. Here's what you need to know.

Things

Everything in Querki is a Thing -- the concept is pretty similar to a typical object-oriented language's notion of "object". If you think in database terms, a Thing is approximately a row. Querki is all about creating and querying Things.
Note that Spaces, Properties, Types and Collections are simply special sorts of Things. The system is as consistent as we can make it.

Spaces

A Space is essentially a database: a whole bunch of related data. Each user may have any number of Spaces. Spaces are human-scale, small by enterprise standards but appropriate for most peoples' day-to-day needs -- the system is optimized for Spaces sized between a few dozen and a few thousand Things. (Eventually a few tens of thousands of Things, but it hasn't gotten a lot of testing at that scale yet.)

Properties

A Property is a characteristic that can be applied to a Thing -- you can think of each Thing as simply a bag of Properties. Properties can include everything from simple Display Names to complex nested data structures. Any Thing can, in principle, have any Property that you choose. Note that Properties are not scoped to specific Models, which is quite different from typical OO languages -- every Property can potentially be added to any given Thing in a Space.
There are a fair number of built-in Properties, but you will usually want to define your own Properties for the Things in your Space. See the Property Reference for the full list of user-available built-in Properties.
User Values: a few built-in Properties -- notably Rating and Review -- are "User Values", which can have a separate value for each User of the Space, and which let you average and summarize those values. This is a general mechanism under the hood: you can build your own User Values of any Type.

Models and Instances

A Model is similar to an object-oriented "class". (In database terms, it is kind of like a table, but only sort of.) You create Instances based on Models, and you can create sub-Models based on parent Models. (In practice, sub-Models are unusual in Querki.) In this way, all of Querki is a big object-oriented tree, with every Thing inheriting from a parent Model, all the way up to the root Thing primitive that absolutely everything inherits from.
However, the inheritance is prototype-styled rather than class-styled. That is, a Model doesn't just say that Instances have a particular Property -- in most cases, the Model actually defines the default Value of that Property. There is no such thing as a null value (or a null pointer exception) in Querki. So when you create an Instance from a Model, it starts out looking just like the Model, until you set its Properties to something else.

Types and Collections

As you would expect, each Property has a Type. The Types are more or less what you expect, although many names have been changed to avoid programmer jargon. The most common Types include:
  • Text and Large Text: blocks of QText (wikitext), which may have embedded QL Expressions. The only real difference between these two Types is that Text shows a one-line data-entry field and Large Text shows an arbitrarily large one.
  • Thing and Tag: a Thing Property is a hard pointer to another Thing; a Tag is essentially a name, which may or may not be the name of an actual Thing. Between them, they are used to express relationships between Things and make it easy to do categorization. Things and Tags are most often used in Sets, and there is special UI support for Thing and Tag Sets.
  • TrueOrFalse: aka Boolean.
  • Whole Number: aka Integer.
You can also define your own Type, by creating a Model and then using it as a Type for a Property. These can, in turn, contain nested Model Types: you can build pretty arbitrarily-complex data structures using them. (This is very advanced stuff, though, and only needed for relatively complex Spaces.)
See the Type Reference for a list of all the Types, which include lots of interesting specialized Types such as Photo, URL, Date and more.
Each Property also has a Collection. There are currently four Collections available:
  • Required: this is what you expect from a typical program variable. It can not be empty -- the Model must define a value for it.
  • Optional: this is called "nullable" in database programming, or Option in functional programming. It says that this Property may have one element, or may be left empty. Unlike most environments, Optional is the default for most Properties in Querki.
  • List: an ordered List of any number of elements of the specified Type.
  • Set: an unordered collection of non-duplicating elements of the specified Type.

Names

Each Thing has three distinct sorts of names:
  • Object ID: by definition, a Thing has a globally-unique Object ID (OID). This is a short string starting with a period -- for example, the OID of this page is ".3y285h4". OIDs never change, so they can be used as reliable, permanent handles for Things.
  • Name: most Things use the Name Property; it is not always required, but it is recommended when it makes sense. This is a more or less arbitrary string.
  • Link Name: the Link Name Property is a "safe" name, unique within this Space, which is used in URLs and QL expressions. It is usually automatically derived from Name, by stripping out any illegal characters and de-duplicating.

History

Querki is mostly version-controlled; this is automatic, as in a typical wiki. If you own a Space, you can get to that Space's History from the Actions -> Advanced... menu pick. Currently, that allows you to browse the Space in a previous state, and revert the entire Space to a previous state if something's gone horribly wrong. We'll eventually provide finer-grained undo changes and the like; the important part is that everything's being tracked under the hood.
(Note that Conversations are not version-controlled, nor are User Values yet. But normal Things and Properties all are.)

Display

Entering data into Querki is only half the story: querying and displaying it is just as important. The task of doing that is handled through three major concepts: Text Properties, QText and QL.

Text Properties and Default View

As mentioned above, a Property of Type Text or Large Text is a block of text; more importantly, Text Properties are most of how you format and query your Space.
In particular, each Thing has a Property named Default View. As the name suggests, this is the "view" that you see by default when you look at this Thing. You can define alternate views, but that's unusual -- most of the time, you use Default View to say what this Thing should look like.
For simple wiki-style pages, you can define the Default View per-page. (That is how this page works.) But most of the time you are dealing with Models and Instances, and you treat the Default View as a template for your data. That is, you define the Default View on the Model, basically saying "this is how to display an Instance of this Model", and don't change it on the Instances. The Default View incorporates the relevant Properties and QL expressions for this Model. The Instances inherit that Default View, and add their own Property Values, which are filled into that template when you look at the Instance.
For a typical example, see Text, Large Text and the Default View from the Learning Querki book.

QText

The bulk of the contents of the Default View is the markup language QText. Full details can be found in the QText Reference, but suffice it to say that it is a dialect of the popular Markdown language, which is used in many wikis. Don't count on any specific feature being identical -- QText is evolving rapidly, sometimes in ways incompatible with Markdown -- but QText is still about 80% similar to Markdown.
This QText acts as a template, providing the text and the formatting in a very similar fashion to the way that template engines like Rails or PHP do with HTML. Inside that QText, you drop in QL expressions, which are queries that display the actual data. Everything inside of [[double square brackets]] is a QL expression.

QL

The QL programming language has been developed entirely from scratch, based very strongly on the idea that Easy Things Should Be Easy. The result is that the most common expressions are tiny -- indeed, they don't even look like programs, but are simply names being interpreted in-context. The considerable majority of expressions are less than one line.
That said, QL is an increasingly sophisticated (if idiosyncratic) pure-functional programming language. While the core is very simple, it includes rich concepts like locally bound values and functions, and should be powerful enough to serve your needs.
See the Introduction to QL for more details on the syntax of the language, More about QL for the gory details and the really advanced stuff, and the Function Reference for a list of all the Functions currently available for use in QL. More Functions are being added almost every week; if you find one that you need, please ask for it.

Finding Your Way Around Querki

There's a lot to Querki, and the best way to learn it is to simply start trying things and kicking the tires. If you've just joined, I recommend creating a Scratchpad Space that doesn't contain any important data, and using that to experiment.

The Querki button

At the top left of the page, you should see the Querki logo. Clicking that takes you to the main Querki page, which if you are logged in shows a list of all of the Spaces that you own, as well as other peoples' Spaces that you are a Member in. This is the quick and easy way to keep track of your Spaces.

The Menubar

Most of the interesting functions of Querki can be found in the menubar at the top of the page. Here is a rundown of what you will find there.
Note: if you are using Querki on a small screen such as a mobile phone, you will see a button at the top right of the page. Pressing that will display the menus described below.

Personal Menu

At the right-hand side, if you are logged in, you will see a menu titled with your display name. That contains:
  • Your Profile: shows the basic information about you, and lets you change your password or display name.
  • Your Mode: Querki has three "Modes", currently named Participant, Builder and Programmer. The only difference is how much of the system gets shown to you: Participant is a very stripped-down, easier to understand view; Programmer gives you all the bells and whistles; and Builder is in-between. You can switch between them at any time.
  • Log out

Actions Menu

For the time being, most of the interesting stuff that isn't directly in-page is in the Actions menu. This contains (in Programmer mode -- some of these are missing in the other modes):
  • Design a Model: this is how you build data structures in Querki. It pops up a dialog that lets you choose which super-Model to use as your base ("Simple Thing" is typically correct), and then opens the Model Designer on your newly-created Model. In Model Designer, you name your Model, give it a Default View, and most importantly add Properties to it. The "Add Property" button allows you to either use a pre-existing one, or create a new Property that you want. The Model Designer is divided into Instance Properties, which you expect to set separately on each Instance, and Model Properties (such as Default View), which are the same for all Instances. In a typical Space, you will want to design 1-10 Models, with a bunch of custom Properties.
  • Create any Thing: this allows you to create an Instance of any Model. There are also a number of more-convenient hooks for creating Instances -- from the header of the Model; from the All Things listing; and the "Create Another Instance" button in the header of Instances.
  • Show all Things: displays all of the Things in this Space, as an inheritance tree. This is similar to the default display of the Space itself, but the Space's Default View can (and often should) be customized to show something else. This menu pick lets you always get to the full list. You can create Instances from the Models shown in this display.
  • Show all Properties: this lists all of the Properties defined in this Space.
  • Sharing: this menu pick is only enabled for the owner of the Space. It allows you to invite people to join the Space, and manage their "role", which is the easy way to control their rights within the Space.
  • Advanced...: this is basically the dumping-ground for power-user features that aren't used very often. At the moment, this contains CSV export, control over whether you receive Notifications in this Space, a button to get to the Space's History, and the button to Archive this Space away. (There isn't yet a way to hard-delete a Space, but Archive is close to delete.)
  • Advanced Edit: this opens the Advanced Editor on an Instance, which is essentially the same as the Model Designer. Not as easy to use as the Instance Editor (which can be reached with the Edit button in the header of most Instances), but more powerful.
  • View Source: this is one of the most useful tools for learning Querki. View Source allows you to see the Properties of the Thing you are looking at. Using View Source on various pages of complex Spaces like this one or the Issue Tracking Space can give you lots of examples of how to do sophisticated things in QL.
  • Security: this is only enabled for the owner of the Space. It allows you to manage fine-grained permissions on this Space (and everything in it), this Model (and all of its Instances) or this Instance, depending what Thing you're looking at. You can usually ignore Security -- the Roles available from the Sharing page are usually good enough -- but Querki provides very fine-grained security when you need it.
  • Explore...: Querki Explorer is the interactive query page. When you click on Explore, you get a page rooted on this Thing, which allows you to type QL expressions and see what they produce. It is basically the REPL (Read-Eval-Print Loop) for Querki, and is very helpful when you are trying to build complex QL, or simply want to do ad hoc queries. Once you've got a complex query you like, this also provides a one-click way to turn it into a permanent page.
  • Print...: while you can print from the browser's own menu, this loses some key features. (Mainly because we can't reliably intercept and enhance the browser's Print command.) So you should usually Print from the Actions menu, which allows advanced Querki features like Print View to work.
  • Delete: if you are allowed to do so, this lets you delete this Thing. Note that you are only allowed to delete a Property if there are no Things using it. (Eventually, we will allow you to delete a Property and remove it from all Things with one command, but that is dangerous enough that we don't want to do so casually.)

Search

The Search box in the menubar is pretty much what it looks like -- it does a simple plaintext search across this Space. For the time being this is pretty simplistic, but it is often the quickest and easiest way to find what you are looking for.

Notifications

To the left of the Search box you will see a bell icon. Most of the time it is black; sometimes it is white, with a number next to it. This is the Notifications Icon, and works similarly to the one found in Google+, Facebook, Spotify and other major online tools. If it is white, that indicates that you have new Notifications; clicking on the icon takes you to a page showing your recent Notifications.
For the time being, the only common Notifications are sent when someone comments in this Space. By default, the Owner receives a Notification for each comment. To turn this Notification on or off, use the Actions -> Advanced... page.

Buttons

The buttons you will commonly see scattered around Querki include:
-- edit this Thing.
-- create an Instance of this Model.
-- refresh this page. (Similar to the browser's refresh button, but much faster.)
... -- create another Instance of the same Model as this Thing. (This seems a bit odd, but can be very useful when you are creating a bunch of Instances of the same Model in a row.)
... -- bulk-edit all Instances of this Model. This also allows you to create new Instances; for most ordinary Models, this is the easiest way to blow in a low of data quickly.

Getting Started

As with any programming environment, the easiest way to figure it out is to start playing with it. I recommend roughly this approach. Things are still a bit manual, and the workflows need work, but it's already far easier than working in most databases.

Choose a Problem

Choose a fairly simple bunch of data to organize. I am partial to listing a CD collection as a good example, but there are lots of possibilities. Ideally, it should be a problem that you would model in an OO programming language with a few distinct classes.

Build Models

In a Sandbox Space, build your Models -- one for each class you would use for this problem in a programming language, or one for each table you would use in a RDBMS.
To create a Model, select Actions -> Design a Model, and use Simple Thing as the base Model. This will kick you into the Model Designer.
In the Model Designer, give the Model a Name.
Add Properties by pressing the "Add a Property" button at the bottom, and select "Create a New Property instead". Give each Property a name, choose its Collection (Exactly One, Optional, List or Set) and its Type. When you press the Create button, it will create the Property and add it to the Model; you can specify the default value for the Property there, and edit meta-Properties of the Property if there are any. You can rearrange the Properties by drag-and-drop, to separate the Instance Properties (which should be different for each Instance) from the Model Properties (which are the same for all Instances), and to change the order they show up in the Instance Editor.
When you are finished adding Properties, press Done. You should see your newly-created Model.

Add Some Data

Using the buttons on the Model's page, create an Instance, or press the bulk-edit button to create lots.

Make a Better Display

Once you have a little data, start playing with the Default View in your Models. Remember, this is just a template. Use QText (wikitext) constructs for formatting, and [[My Property]] to display the value of My Property.

Iterate

One of the nicer aspects of Querki is that it is designed for evolving data. Add additional Properties, and mess around. Not all refactorings and changes are possible yet, but we're gradually moving towards making this a nicely fluid environment.

Feedback

Questions and opinions are totally welcome. We'll eventually have proper forums, but in the meantime please feel free to drop me an email, or ask questions in the development journal. If you want to get more deeply involved, say so and I may be able to add you to the Issue Tracking Space, which is where I'm managing the project.

Conclusion

It is early days yet, but Querki is starting to really work properly. Welcome to the community, and I hope that you'll choose to get involved.