Evaluating a QGraph query returns a container, a collection of all the matching subgraphs from the database. To match the query, a subgraph must have the correct structure and satisfy all of the query’s requirements (conditions, numeric annotations, and constraints). This chapter covers how query structure matches database structure; conditions, numeric annotations and constraints are covered in subsequent chapters.

It’s important to understand how the structure of a QGraph query matches database structures. Let’s look at an example database fragment and see how a simple query matches that fragment. Figure 2.2 shows a fragment of a database containing information about books, movies, and writers. We can see that this fragment includes three different types of objects, as represented by the different values for the ObjType attribute. Similarly, the LinkType attribute describes the type of relationship that links two objects in the database. Additional object attributes provide more details about the objects, such as a person’s name or a book’s publication date.

The query shown in Figure 2.3 finds two objects connected by a directed link. It will match any database subgraph with this structure.

Executing the query on the database fragment shown above yields the four subgraphs shown in Figure 2.4.

The database fragment in Figure 2.2 includes four different instances of two objects connected by a directed link, which correspond to the four subgraphs in the query results. Each match to the query yields a separate subgraph in the results container, for example, the two links between Stephen King and Storm of the Century create two different matches to the query and therefore two different subgraphs in the query results. Importantly, the query returns subgraphs that include all related object and link attributes. Query results retain the vertex and edge names used in the query. These names are used only in the context of the result subgraphs; they are not added to the database objects or links themselves.

Let’s examine the results of a slightly more complicated query run on another database fragment, shown in Figure 2.5. This time our fragment contains information on movies and their casts. In particular, we see that Elizabeth Taylor appeared in Butterfield 8, that both Elizabeth Taylor and and Richard Burton appeared in Cleopatra, and that the two actors were married to each other.

This time, our query finds all subgraphs that have two objects linked to a third object. Both links must be directed and must point to the third object. The new query is shown in Figure 2.6.

The results of executing this query on the above database fragment are shown in Figure 2.7.

Because QGraph finds each unique match of the query’s structure, the query’s results can include subgraphs that contain the same database objects and links but which are mapped to different query elements. This can be seen in the top two subgraphs in Figure 2.7. Both subgraphs contain the objects Elizabeth Taylor, Richard Burton, and Cleopatra and their associated acted-in links, but they correspond to different vertices and edges in the query.

Additionally, QGraph does not require that distinct query elements match distinct database entities, therefore database elements may appear more than once in an individual subgraph if they correctly match the query’s structure. In this example, the last four subgraphs include duplicated objects and links. Although they correspond to the same database entity, such duplicated objects and links are treated as distinct entities within the subgraph because they match distinct query elements. Query constructs such as conditions, numeric annotations, and constraints, introduced later in this guide, can be used to restrict matches and avoid this kind of duplication in query results when desired, but the query structure alone carries no such requirement.

Just as important as what a query returns, is what it doesn’t return. Note that the first two subgraphs in Figure 2.7 do not include the married-to link from Richard Burton to Elizabeth Taylor. QGraph does not return links in the database that are not specified in the query, even when both link ends are in the same subgraph.