Wylib DataBase Search widget (DBS)


Table of Contents

Introduction
How Query Logic Works
Building the Query Logic
Pattern Matching
Regular Expressions
Wildcard
Saving a Query for Later
Sharing Your Queries with Others
Joining More Tables Into the Query

Introduction

This widget is generally used in conjunction with a DBP preview widget in order to choose a select group of records to be loaded into the preview. You should understand the help file for DBP before reading this manual.

Like many other widgets, it will have a menu near the upper left corner of the widget where you can find the available functions for the widget. The title on this menu is typically "Query Builder:" indicating that you can use the widget to ask (query) the database for the records you want.

The widget window is divided into two main sections. The top section is used for building a "logic phrase" that will describe to the computer what records you want to fetch from the database. The bottom section is used for adding more tables to the query so you can ask for records that are related to data in other parts of the database in various ways. So for many simple queries, you can ignore the lower part of the window (Tables/views:).

How Query Logic Works

In order to fetch records from the database, you need to describe to the computer which records you are looking for. If you were describing it to another person, you might say the phrase: "Please give me the records of all employees who were hired before last January."

If you needed to be more specific, you might say something like: "Please give me the records of all employees who were hired before last January and who are male and are paid hourly."

In this last phrase, the word "employees" tells us which table to look in. And then there are 3 separate clauses that tell us which employees to fetch the records for:

  1. hired before last January; and
  2. are male; and
  3. are paid hourly

Notice that the clauses are joined with the word "and" so all the conditions have to be true in order for the employee to be included in the query.

Think how much different the results might be if we used "or" instead: "Please give me the records of all employees who were hired before last January or who are male or are paid hourly."

The table is the same, and the clauses are the same, but if any one of the clauses is true for a given employee, that employee will be included in the query.

When building a database query, we will follow the same form as in these verbal queries. The query will consist of a number of clauses, each of which refers to one of the columns in the table, specifying which records to include in the query based on the data in that column.

Building the Query Logic

The query clauses are entered in the upper pane of the widget, with each one appearing as a line of buttons and entries where you can set the parameters of the clause. When you first open the widget, there may not be any clauses visible. Or, there may be some left over from the last time you used the widget. To get a fresh start, you can press the Reset button and the widget will be reset to a single, blank clause.

If you want to add more clauses, press the "More" button. If you want to have less clauses, press the "Fewer" button.

Each clause line contains (from left to right) the following widgets you can use to set the parameters for the clause:

Table/Column:
This pull-down menu allows you to choose the table and column you want to refer to in your query criteria. For example, you might want something like "Employees->Hire_date" to get the first clause of the example query in the previous section. To keep things simple for now, always assume we are querying from a single table so the tablename will always be the same. When you get to advanced usage, you will be able to have each clause choose from multiple tables and/or views in the database.
Negation:
This button is usually blank. But if you press it, it will toggle to show the word "Not." This can be used to negate (reverse) the sense of the comparison. For example, it can change "all employees hired before last January" into: "all employees NOT hired before last January."
Comparison:
This pull-down menu allows you to choose one of several different comparison operators. For example, when implementing the clause: "hired before last January," you would want to select the "Less Than" operator. This would allow you to find all "hire dates" that are "less than" (or before) a date you specify in the next field. The "regex match" and "wildcard match" are ways of matching multiple records using a kind of "shorthand" notation and are described in the section on pattern matching.
Constant Value:
This is an entry field that only appears if the pull-down menu to the right of it is set to the value "Constant." In this entry, you can type the value you want to use for the "right side" of the comparison. For example, when implementing the clause: "hired before last January," you would type in something like: "2006-Jan-01".
Right-hand Table/Column:
This field serves the same purpose as the Constant Value field (it is the value being compared to). However, rather than a fixed value that you type in, it can reference another database table and column. This would be helpful in comparing two database fields with each other. For example, "Show me all employees who are older than their supervisor."
Case (ca/nc):
This button toggles when you press it. When it says "ca" this means that case (upper case / lower case) will be considered when matching words to each other by the applicable comparison operators. When it says "nc" case will be ignored in the comparisons.
Conjugation Operator (and/or)
This button only appears when you have more than one clause line inserted in the phrase. It serves the purpose of joining clauses with "and" (all clauses are required to be true) or "or" (any one clause is required to be true).
Indentation:
When the Conjugation Operator appears, there are also two small arrows to the left of it. These control the "indentation" of the clause before and after the conjugation (and/or) operator. This is used in advanced queries for "grouping" certain comparisons together. For example consider grouping the and/or this way: "Please give me the records of all employees who were hired before last January and (who are male or are paid hourly)." To accomplish this grouping in the logic building, you would simply indent the "or" between the last two clauses one space to the right and leave the "and" between the first two clauses unindented.

So to build your query, first determine how many clauses you need. (How many columns will you be considering in your query?) Press the More button enough times to produce the right number of clauses. Then select the table, field(s) and comparison operators to describe your query.

When you are ready to run the query, press the Search button. The resulting records from your search will be loaded into the associated preview widget.

Pattern Matching

Sometimes it is nice to match a record based on only a partial match. For example, you might want to load all people who have the letters "er" in their name. This kind of search is called a pattern match because you are looking for the pattern of characters "er" rather than the exact name "er."

The system supports two kinds of pattern matching, regular expressions and wildcards.

Regular Expressions

In regular expressions, most regular characters just match themselves. The pattern you enter will be matched if it occurs anywhere in the match string. So, in the example, you could just enter "er" and all records with an "er" anywhere in the selected column will be returned.

You can also use the special character "." (period) to match any single character. For example, "e.a" will match the pattern of an "e", followed by any character, followed by an "a".

Another common character is "*" which means "zero or more in a row." So "a*" will match any number of consecutive "a" characters.

There are many more ways to use regular expressions. If you would like more detailed information on this, try this tutorial.

Wildcard

Wildcards are very similar to regular expressions, but the match characters have a little bit different meaning. For example, the "*" character is used to match any arbitrary "chunk" of text. Also, wildcards are expected to match the whole string--not just a portion of it. So if you wanted to find all names with an "er" in them, you would have to specify "*er*" as your match string. This would match "any chunk of text" followed by "er" followed by any other chunk of text.

There are many more ways to use wildcards. If you would like more detailed information on this, try this tutorial.

Saving a Query for Later

Once you get a query working just the way you want, it is helpful to be able to save it. Under the widget menu, there is an option called "Save Query." When you press this, it will ask for a short-hand name and a description for the query. Then it will save your query to the disk so you can recall it later.

When you want to run your saved query, you can choose the menu option "Load/Run Query" or press the Query shortcut button. This will ask you to select one of your saved queries and then it will load and run that query.

Sharing Your Queries with Others

The menu option "Export Query" is much like "Save Query" except it will write the saved query to a filename you specify. Then if you put that file where someone else can read it, they can use the "Import Query" option to load the same query into their application.

Joining More Tables Into the Query

Not yet written. (Volunteers?)