Query API

The Query API provides some classes and methods for requesting and handling answers to arbitrarily complex questions posed to a Cyc server. Query objects specify such requests and store the answers, and can be constructed by specifying a query sentence with zero or more open variables, an optional microtheory, and other parameters to guide and control the inference process. Alternatively, predefined query specifications can be loaded from a Cyc KB, or natural language questions can be used to produce Query objects that can then be modified or combined prior to being run. Inference answers can be inspected, with representations of variable bindings in CycL and NL, and complete CycL sentences for each answer. They can also be iterated over using a SQL-style result set, and can be exported in CSV or XML formats. Each of the main packages in the Query API provides a specific piece of query-related functionality.

com.cyc.queryRun queries against a Cyc server and review the results
com.cyc.km.query.constructionConstruct CycL queries on the basis of English query strings
com.cyc.km.query.exportExport the results of a Cyc query into CSV or XML
com.cyc.km.query.answer.justificationProvide justifications for inference results

Asking a Query

com.cyc.query.Query provides the main functionality for running queries against a Cyc server. Constructors allow Queries to be created from CycL sentences (both as Sentence objects and as Strings), as well as from stored queries in the KB (i.e., using the constructor that takes a KBIndividual). Answers from the Cyc query can be retrieved using isTrue, isProvable, getResultSet, getAnswers, and related methods.

One crucial thing to note about the Query class is that if a query is either browsable (c.f. setBrowsable) or continuable (c.f. setContinuable), it is up to the Java application developer to close() each of the Query objects when finished with it. Continuable and browsable query objects are wrappers around server-side query objects and, if not properly closed, they will lead to a potentially severe memory leak.

Constructing a Query from English

The package com.cyc.km.query.construction is designed to allow the construction of CycL query sentences based on natural language strings. It does not provide a completely automated "English --> CycL" translation capability, but instead provides a way of generating small query "fragments" that can be combined, with the guidance of a human, into a relevant CycL query. The QuerySearch class provides methods that allow a UI to show which fragments were produced from which parts of the input string, thereby making it clearer to a user how the fragments are related to the input. Fragments produced this way can be combined into larger queries using some of the methods on the Query class (e.g., merge, findConnectedClauses and others).

Exporting Query Results

The package com.cyc.km.query.export provides an abstract ResultsExporter class, for exporting query results, as well as two reference implementations of it for CSV and XML formats. Exporting works by outputting a document to a PrintWriter, PrintStream, or String, consisting of a header, a section describing the query, a section enumerating the answers, and a footer.

Explaining the Rationale for an Answer

The com.cyc.km.query.answer.justification package provides support for generating structured explanations for inference answers. A justification object can be constructed using new ProofViewJustification(InferenceAnswer), for any answer returned by Query.getAnswers(). The justification has a tree structure, whose root node is returned by getRoot(). Each Node has associated CycL and NL (formatted in HTML) that can be rendered in an interactive interface, as well as accessors to get its parent and children nodes. Additionally, an entire Justification can be exported to XML via the ProofViewMarhaller class.