Graphical Query Editor Tutorial

Prolegomena - Collections, Keyboards and Fonts
Lesson 1 - The Basics
Lesson 2 - Greek Syntactical Searches
Lesson 3 - Advanced Concepts

The purpose of this tutorial is to teach the art of query design on the Graphical Query Editor.

The examples which follow will use the Nestle Aland 27th edition of the Greek New Testament with the GRAMCORD™ Alpha morphology. The basic design principles are the same regardless of which text you are searching, but using the NA27 allows me to show off many features of the search engine, and give a taste of how to combine some of the simple search criteria into more complex queries. Most of these searches will run on an older version of the Gramcord morphologically tagged NA 26 or 27 or the LXX, but the more advanced searches that take advantage of new features will return false hits. You may find it beneficial to make sure you have the latest version of the NA27 by running Libronix Update. If you don't already own a license to the NA 27, you may purchase one here.

NOTE: the query editor can be used with any book in your Libronix Digital Library System for simple as well as complex searching; I just chose to use real world Greek Bible examples to demonstrate the flexibility and power of the new search tools.

Before we begin - a look at collections, keyboards and fonts.

Collections

I find it helpful to create collections to represent the different groups of resources I might want to search using the Graphical Query Editor. It's convenient if I want to search all the texts that share a morphology scheme (like searching the LXX at the same time as the NA27), and it is very handy if I go to run a search without remembering to open the resources I wanted to search first - collections always appear as options in the advanced search dialogue. To create a collection for searching the NA27, perform the following steps:

1. Click Tools | Define Collections.
2. Click New.
3. Type NA27 in the name field.
4. In the find textbox, type in NA27 and select the Nestle-Aland Greek New Testament, 27th edition with GRAMCORD (tm) Greek New Testament Alpha Morphological Database. Then click Add.
5. Click OK.

This is an example of a one-book collection. Now every time you go to execute a search, you'll have access to this collection, even if you haven't opened this particular bible. You might make another one called 'Gramcord' and include all your Greek Bibles that use the Gramcord morphology and collections for your morph tagged Hebrew resources as well. The rule of thumb is to create collections for the books that you plan on searching on a regular basis from the query editor--it'll save hassle later.

When you are done making all your collections:

6. Click Close.

Keyboards

Libronix DLS 3.0 has three different keyboard options for Greek: Windows, LLS and Logos. The 'Logos' keyboards are new to LDLS version 3.0, and represent an intuitive way to enter Greek and Hebrew from a Roman/English keyboard. For purposes of this tutorial, let's make sure we're all using the same one. In the rest of the tutorial, when you are required to type Greek, I am going to provide the actual Latin/English characters you need to type in this keyboard map to get the word in question. Remember when working with your own queries that you can also copy and paste directly from your Bible, lexicon, or other Libronix resource into the query editor.

1. Click the Tools drop-down and select Options | General.
2. Click the Interface tab.
3. In the Keyboard Layout dropdown box, select Logos.
4. Click OK.

Fonts

Finally, you are now able to select which font you wish to use for working with Greek and Hebrew. Mostly this is personal preference, but you will notice that some fonts are missing some characters, so if you get white boxes in your Greek text, you might try an alternate font. While fontmaps from some older fonts like Graeca II will allow you to use some non-Unicode fonts, Unicode fonts will, in general, look and work better. For an article on Unicode and Fonts in Libronix, along with links to some of the popular Greek fonts available on the Web, click here. To select your font, perform the following steps:

1. Click Tools | Options | Bible Tools.
2. Select the Ancient Languages tab.
3. By selecting various fonts from the drop down boxes, you can view the sample text in that font. Choose the font(s) you like best. Try to stick to the fonts that display in the drop down list, rather than selecting Other which will can you down the path of non-Unicode fonts. Note that some Greek fonts are missing the most-correct Unicode character for the apostrophe, so if you see white boxes where you expect apostrophes, switch to a different font. I often use Gentium or Gentium Alt for my Greek font, which contains the correct apostrophe.
4. Click OK

Lesson 1 - The Basics

Let's start our first query. In the rest of the tutorial, I'll list the goal of the query at the beginning, but in this query we're going to play with a number of different options, so just hang on for the ride!

1. Click the File drop-down menu and select New.
2. If it isn't selected already, select Graphical Queries. You may choose to give your query a name now, or you can accept the default name for now and name the query later when you close it. I prefer to name the query when I close it because I'm given the opportunity to delete the query at that time. This saves having to manually delete a query that isn't worth keeping later, but either method works. I've named this first query 'Lesson 1', as you'll be able to see on the screenshots. When you are done naming your query document, or if you choose not to name it now, click OK.

This opens up a new window in LDLS labeled Graphical Query: with the name (the one you specified or the default) at the top. In the grey bar on the left are a number of objects that you can click and drag onto the white space that is our query document.

3. Click and drag a TERM object onto the query document. This brings up the TERM editor window. Check the Language box and choose Greek from the drop-down list. You'll notice that this opens up two large white boxes inside the term editor. The left box will auto generate a list of Greek words to choose from as you start typing, while the right window will display a KeyLink definition for that word (if one is available). These are simply aids to assist you in selecting the words you want--you may search for Greek words that are not on this list (though all the words occurring in the NA27 should be). Hebrew has a similar interface; for other languages, you won't have these additional information boxes.
4. Press the F2 key twice to toggle your keyboard to Greek. Pressing it once changes from English to Hebrew, pressing the second time toggles to Greek. You will press it a third time when you want to toggle back to English.
5. Type in the letters (following the English keyboard) kuriov. You'll see the Greek word κυριος (eng. lord, master) appear. Note that before you finished typing, you could have clicked on the word in the list on the left.  

If you have a Greek Lexicon in your library, clicking on the accented form, κύριος, will reveal a lexicon article in the right information box. However, unless you check the Match Marks box towards the bottom of the Term Window, the search won't be concerned about Greek accent marks no matter which form you select or type.

6. Click OK.

You've just finished your first query. This document as it stands will find all occurrences of the Greek word κυριος. To execute this query:

7. Click the Search button in the Graphical Query window. This takes you to the Advanced Search dialog. Your active query is already selected for searching, but there are a few options to examine.
8. In the In: section, click on the radio button that says Resource Collection. From the drop down menu, you can now choose the NA27 collection we created earlier. Now the query knows what resources you want searched.
9. In the By: section, let's just make sure Bible Verse (the default) is selected. Later we'll want to do some searching using other criteria, such as sentence, listed in a drop down box once Special is selected, but for this simple query, the results will be the same no matter which discourse level is selected.
10. If under Range: you select Bible Text you will avoid searching footnotes or introductory material. You can also limit the verse range you want to search. However, a note on ranges: when searching a book that only contains the New Testament, like the NA27, if you want to search the entire NT, leave the range at Bible--it will actually slow the search down slightly if you make the search check that hits are within the NT range.
11. Now click Search. You'll get a list of all the verses which contain the word κυριος. Clicking on the verse number will jump to your preferred bible, but clicking on the box in the column underneath the NA27 label will jump to the specific bible we searched, in this case the NA27.
12. Go ahead and close that search results window, but don't close the query document--we're going to try a few new things with our query.
13. Click and drag another TERM object onto your query document. Dropping the new TERM object on the document opens up the TERM editor window.

Design Principle: It never matters where you place a TERM object in the document. The actual placement of the items on the screen is stylistic, and does not affect the query results. If you decide you didn't like where you dropped an object, just click and drag it somewhere else. Since the query editor is designed to help you visualize exactly what you are searching for, it is good practice to place TERMs close to the other TERMs, REFs, or operators that you are going to connect them to, but placing a term to the left or right of another has no effect.

14. Click the Language check box again--Libronix remembers that you used Greek last.
15. Type in Ihsouv, Ιησους - the Greek spelling of the name Jesus. Click OK.

Design Principle: This brings us to one of the important principles of Query design. When you have two terms, or two groups of terms in a more complex query, that are not joined by any arrows to each other, the default relationship between the terms is an OR. So simply by adding this new term, our Query has been transformed into an OR statement, which will now return any verse that contains EITHER κυριος OR Ιησους. In more advanced queries, you may need to use the explicit 'OR' operator in the menu to the left of your query, but this query is 'OR'ed now simply because the terms are not connected.

If you wish, execute this new query by following steps 7-11 above.

Let's start experimenting with other types of relationships between these terms.

16. Click and drag the AND operator onto the query document.
17. Hover your mouse on the edges of the word κυριος and move it around until you see a grey arrow. Click and hold the left mouse button to activate the arrow, and drag it over to the AND operator, and release the mouse button to complete the line.
18. Hover your mouse on the edges of the AND operator in the same manner and drag the new arrow to the word Ιησους. Notice that the direction of the new arrow reversed. This bring us to another...

Design Principle: When drawing arrows between terms and operators, or between two operators, the direction of the arrow must always point TO the governing operator. In the example above, Libronix auto-corrected the direction of the arrow for you - it didn't allow an invalid query. But in more complex queries, it is possible to link up operators with arrows going the wrong direction, which will return results opposite of what you are searching for. This will be illustrated in the steps that follow.

Again, if you wish to execute your new query, with the explicit AND operator instead of the previous implicit OR, you may do so by following steps 7-11 above.

19. Click and drag a new TERM object onto the Query Document.
20. Click the Language box again. Enter the word Cristov (Χριστος, eng. Christ) and press OK.
21. Click and drag the NOT operator into the Query Document.
22. Draw an arrow between Χριστος and NOT. Again, since you are drawing between a TERM and an OPERATOR, the arrow direction will auto-correct if you draw it wrong--the arrow must point to the governing operator.
23. Now draw a line from the NOT operator to the AND operator.

This new query will find every verse that contains both Ιησους and κυριος, but does NOT contain Χριστος. When you are drawing arrows between operators, it is possible to draw the arrow in the wrong direction. Had you drawn the arrow from the AND to the NOT, you would be searching for every verse that did NOT contain Χριστος and also did NOT contain the combination of BOTH κυριος and Ιησους (but would return verses that had just the one or the other).

Again, to execute the query as it now stands, follow steps 7-11. Feel free to try searching with the arrow reversed as well if it helps you to see what I described in the above paragraph. But since that search returns most of the New Testament, it is pretty slow!

24. If you played around with switching the direction of the arrows, make sure that the NOT is pointing to the AND again.
25. Click on the arrow that connects κυριος and the AND operator. With that line selected, press the Delete key. Deleting elements of your query is as simple as that, just highlight and delete.
26. Delete the line connecting Ιησους and the AND operator.
27. Drag and drop the OR operator into the query editor.
28. Draw a line from κυριος to OR.
29. Draw a line from Ιησους to OR.
30. Draw a line from OR to AND.

This demonstrates the use of the explicit OR operator. Remember that unconnected terms or groups of terms are implicitly ORed, but in this instance, we are searching for κυριος OR Ιησους in verses that do NOT contain Χριστος. What would happen if you drew the arrow from the AND to the OR instead? Your search would return every verse that either a) contained Ιησους or b) contained κυριος or c) did not contain Χριστος. Verses that DID contain Χριστος but also had Ιησους or κυριος would be returned, because the NOT Χριστος was just part of a larger OR statement, and thus an optional criteria rather than a required one.

You know the drill by now... Feel free to execute the new query.

Now we are going to play with some new ways of defining relationships between search terms.

31. Highlight the AND operator. Press Delete. Notice that deleting the operator also deletes the arrows connecting to it.
32. Delete the OR operator.
33. Delete the NOT operator.
34. Now draw an arrow from Ιησους to κυριος.

Notice the direction of the arrow. This arrow is specifying the order in which the connected terms must appear. In the screenshot, my arrow is pointing from right to left, but the TERM the right must come before the TERM the left in our search - the direction of the arrow, not the arbitrary order of the TERMs in the query document, is what determines the word order being searched.  What you've just told the Query engine is that you want to find all verses where Ιησους occurs BEFORE κυριος. Furthermore, you want the Engine to also return all verses that contain Χριστος. Can you remember why? Because Χριστος is not connected to the other search terms by any arrows or operators, a relationship of OR is implicit.

Design Principle: Drawing an arrow between search terms is an implicit AND operator, so you do not need to connect Ιησους and κυριος with an explicit AND. Indeed doing so unnecessarily complicates your query. Remember the implicit AND of the arrow between terms and the implicit OR of isolated terms, and avoid putting redundant (or contradicting!) operators into your queries.

By default, the arrow between search terms doesn't specify the distance between the search terms, only the order.

35. Double-click on the arrow between Ιησους and κυριος.

This brings up the Proximity editor window. This allows you to specify ranges between search terms, such as At most 20 characters intervening or At least 3 words intervening. Note that the Words unit is an estimate, not a precise word count--it is designed to help people think in terms of rough word ranges instead of characters. Adjacent is used to specify that the second term must immediately follow the first. We will explore uses of the Same option in the next lesson, so don't worry about it for now.

36. Click the box entitled Ignore order of terms.
37. Click OK.

Notice that the arrow now points both directions. Since we didn't specify a range, and we now don't care about the order of the search terms, this double-headed arrow will behave exactly like the AND operator.

38. Now draw a new arrow from Ιησους to Χριστος.

If you were to run this query, it would return all verses where Ιησους occurs before Χριστος AND the word κυριος appeared anywhere in the verse. κυριος might appear either after or before the Χριστος, as there is no line between κυριος and Χριστος to define proximity relationships between those terms, and the double ended arrow between κυριος and Ιησους tells the engine not to worry about the order of those terms. Can you guess how you would specify that both Ιησους and κυριος must appear before Χριστος in your hits? Simply draw an arrow from κυριος to Χριστος. (Feel free to experiment with this, or any other tip in the non-numbered instructions, but make sure to use the Undo button to undo any changes you make that aren't part of the numbered instructions, so that we stay together. The Undo arrow is the little curved hook that points to the left on the main toolbar.)

39. Repeat steps 35-37 on the new arrow. When you are done, this new arrow should also point in both directions.

Running this query would return every verse where all three terms, Χριστος, κυριος, and Ιησους appear.

40. Double-click on the search term Χριστος.

This pulls up the Term editor window again, allowing us to edit the entry. Down at the bottom, there are a number of options. Note that match case simply tells the query to only return hits that match the capitalization of your search terms; it has nothing to do with grammatical case (nominative, genitive, etc.). By default, the Query engine isn't too concerned about accent marks or breathing marks in Greek (since accents in verbs especially can shift depending on surrounding context, this flexibility isn't necessarily a bad thing), but if you ever need the engine to be very specific about the special marks it needs to match, check the Match Marks button.

41. Check the box Exclude Term.
42. Click OK.

Notice that Χριστος now has a red circle around it. This is NOT the same as the NOT operator. This term will match anything that is NOT the word Χριστος. Our present query will still return verses which contain the word Χριστος as long as it can match at least one word in the sentence that is NOT Χριστος. While that renders the use of the 'Exclude' in this search fairly useless, the feature does have some interesting applications when combined with other operators. We will explore one example below.

43. Delete the arrow between Ιησους and Χριστος.
44. Delete the arrow between κυριος and Ιησους.
45. Draw a new arrow from κυριος to Ιησους.
46. Draw a new arrow from κυριος to Χριστος.
47. Draw a new arrow from Χριστος to Ιησους.
48. Double-click on the search term Χριστος.
49. Click Intervening Term.

Intervening TERMs allow you to specify what may, or may not, occur between two regular TERMs (or REFs, which you will encounter in Lesson 2), as in our example where the intervening TERM is connected by two arrows.  If connected with only one arrow to a single TERM, an intervening TERM will specify criteria between the regular TERM and the beginning or end of the document level (verse, sentence, etc. - whichever is specified in the Advanced Search Dialog) depending on the direction of the arrow.

If a search criteria is Required than it must exist between the search terms. If it is Optional then it may or may not exist between the search terms (by itself, an Optional Term/Ref doesn't accomplish much, but this can be combined with Agreement and Proximity operators in fairly powerful ways). If a term is Filtered, then every word between the first and the second search term must meet the criteria of the intervening term. In English, we tend to only think of filters as excluding, but in Query language, a filter can be positive or negative. If you have Exclude and Filter checked, then the word Χριστος cannot occur between the terms κυριος and Ιησους--pretty much what you expect the English word 'filter' to mean. However, if you uncheck the Exclude box, then every word that appears between κυριος and Ιησους must match Χριστος. You will still get a hit if there is no Χριστος in the verse at all, as long as NOTHING is in between the search terms (remember, you would use the Required option if the term needed to be present, not a Filter). But if a word exists between the terms, it must match Χριστος, because our positive (non-excluded) Filter demands it.

In a later lesson, we'll start combining filters with lists of TERMs or REFerences, and it will become apparent how powerful these different features are. For now:

50. Click Filter.
51. Click OK.

Running this query will find all verses where κυριος occurs before Ιησους, without the word Χριστος in-between.

Design Principle: The direction of arrows when dealing with intervening terms/filters is very important. It is nearly always a bad idea to use double ended arrows when dealing with intervening terms (notice how I had you create new one-directional arrows before running the above query). The direction of the arrows to and from the filter should match the direction of the arrows between the two search terms you are adding the filter criteria to. So how would you run a filter in cases where you wanted to be flexible about word order? Take advantage of the implicit OR by creating an un-connected group of search criteria with the arrow reversed. Follow the steps below...

52. Click and drag on the white space of your query till you have drawn a box around your entire query and then release the mouse button. Your whole query should now be highlighted.
53. Press Ctrl+C on your keyboard. This copies the query to the Windows Clipboard.
54. Press Ctrl+V to paste the duplicate of your query back into the same query document.
55. You may click and drag this entire replica to a spot on the query page that doesn't overlap the other query if you need to.

Currently, the Graphical Query Editor does not support a 'Save As...' function. I use the same copy-paste technique to paste whole queries into new documents when I want to save an older query before making major changes.

56. On this second copy, delete all three arrows.
57. Redraw new arrows connecting the terms in the opposite direction.

Running this query will now return all instances where κυριος and Ιησους occur without Χριστος in between them, regardless of the order of the two search terms.

Design Principle: When specifying proximity, it is best to only modify the proximity operators between the basic search terms, not between the regular terms and the intervening terms. Remember that 'optional' and 'filter' terms don't have to exist in the verse for the verse to generate a hit, so giving proximity ranges on optional criteria is likely to skew your results in undesirable ways. To reiterate, don't modify proximity on arrows connecting to or from 'intervening terms'. Indeed, this is the only reason I had you draw the line from κυριος to Ιησους in step 45. If you didn't intend to add any proximity operators, that line would be redundant with the lines going to and from the filter, which are sufficient to establish the order of terms.

To limit our query to verses where the search terms appear close to each other, perform the following steps:

58. Double click the line from κυριος to Ιησους. Modify the proximity to At most 4 intervening and select Words as the unit.
59. Repeat for the line from Ιησους to κυριος on the other half of the query.

Running the query now will only return hits where Ιησους occurs within (approximately) 4 words of κυριος, regardless of the order of those terms, when Χριστος does not occur between them.

This is the end of lesson one. Congratulations, you've learned the basics of query design--how to get a query started, enter Greek search terms, use Boolean AND, NOT, and OR operators, specify order of search terms and proximity, and even use intervening terms and filters.

Lesson 2 - Greek Syntactical Searches

In this intermediate lesson, we'll build on what we've learned in the previous lesson and construct a query that includes Greek Morphological References, Reference lists and the new Agreement Operator.

For this lesson, we're going to search for instances of the Greek syntactical structure Genitive Absolute. Don't worry if you don't know what that is (If you have a decent collection of Libronix titles, chances are good that if you did a search in your library for this phenomenon you could read all about it)--it was just chosen to show off the power of the Graphical Query Editor using a real-world syntactical example. What concerns us here is not the semantic definition of the Genitive Absolute, but rather its syntactical structure, because it is this structur