Using iKnow
iKnow Tools
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The primary iKnow interface for creating a domain and populating it with data is the iKnow Architect. The principal interface for analyzing iKnow data is through APIs containing class object methods and properties which may be invoked from Caché ObjectScript programs. The iKnow tools described in this chapter are meant to assist in maintaining iKnow functionality and in testing and examining iKnow data. All functionality provided here is also available using the iKnow APIs.

The iKnow tools described in this chapter are:
iKnow Shell Interface
The iKnow Shell can be used to return information about existing domains and indexed sources.
All iKnow operations occur within a namespace. Therefore, before invoking the iKnow Shell, you should specify the desired namespace using the ZNSPACE command.
From the Caché terminal you can activate the iKnow Shell interface as follows:
USER>DO $System.iKnow.Shell()
This returns the iKnow Shell prompt. Typing ? at the iKnow Shell prompt displays a list of the iKnow Shell commands. Typing an iKnow Shell command followed by space and a ? displays information about that command.
The iKnow Shell commands and options are case sensitive and must be specified in all lowercase letters.
List, Show, and Summarize Sources
The following iKnow Shell example makes use of an existing domain named “mydomain” in the current namespace. The domain “mydomain” contains 100 sources. The use domain mydomain command specifies using “mydomain”, making it the current domain for the iKnow Shell. The list source command lists the sources in the current domain. By default, a list command lists the first page, with a page size of ten items. To list additional pages, you can specify the > command, as shown in this example. To change the page size to 20 items, specify use pagesize 20.
The show source 92 command lists the contents of source 92, broken into sentences. It lists the first page of 10 sentences; you can use the > command to list additional pages of sentences. The text of each sentence is prefaced by its sentence Id, and is followed by a boolean indicating whether the Shell had to truncate the displayed sentence text. (For the purpose of this example, I have added line wraps to the sentence texts.) The show summary 92 6 command summarizes the contents of source 92 to 6 sentences, and displays these 6 sentences. If the summary number is larger than the number of sentences in the source, show summary displays all of the sentences in the source.
SAMPLES>DO $System.iKnow.Shell()
 
Welcome to the iKnow shell
Type '?' for help
Type 'quit' to exit
 
iKnow> use domain mydomain
Current domain: mydomain (1)
iKnow> list source
 srcId          externalId
   100    :SQL:Accident:96
    99    :SQL:Accident:98
    98    :SQL:Accident:94
    97   :SQL:Accident:100
    96    :SQL:Accident:80
    95    :SQL:Accident:99
    94    :SQL:Accident:95
    93    :SQL:Accident:88
    92    :SQL:Accident:97
    91    :SQL:Incident:90
iKnow> >
 srcId         externalId
    90   :SQL:Accident:93
    89   :SQL:Accident:92
    88   :SQL:Accident:91
    87   :SQL:Accident:85
    86   :SQL:Accident:86
    85   :SQL:Accident:89
    84   :SQL:Accident:87
    83   :SQL:Accident:83
    82   :SQL:Accident:78
    81   :SQL:Accident:82
iKnow> show source 92
 sentId       sentenceValue                                                                  sentenceIsTruncated
   5090       On March 7, 2001, about 1500 Alaska standard time, a wheel/ski equipped 
              Cessna 180 airplane, N9383C, sustained substantial damage during takeoff from 
              a snow-covered area at Ophir, Alaska.                                          0
   5091       The airplane was being operated as a visual flight rules (VFR) cross-country
              personal flight to McGrath, Alaska, when the accident occurred.                0
   5092       The airplane was operated by the pilot.                                        0
   5093       The commercial certificated pilot, and the sole passenger, were not injured.   0
   5094       Visual meteorological conditions prevailed.                                    0
   5095       During a telephone conversation with the National Transportation Safety Board
              (NTSB) investigator-in-charge (IIC), on March 8, 2001, the pilot reported he
              landed near Ophir earlier in the day.                                          0
   5096       When he was planning to depart, the surface of the snow had become crusty.     0
   5097       The pilot said he began a takeoff run toward the south, but the airplane 
              did not become airborne until it was within about 50 yards from several trees. 0
   5098       During the initial climb, the left horizontal stabilizer collided with a 
              spruce tree about 25 feet above the ground.                                    0
   5099       The airplane began a descending left turn toward the ground, and collided
              with several trees while the pilot was making an emergency landing.            0
iKnow> show summary 92 6
 sentId       sentenceValue                                                                  sentenceIsTruncated
   5090       On March 7, 2001, about 1500 Alaska standard time, a wheel/ski equipped 
              Cessna 180 airplane, N9383C, sustained substantial damage during takeoff from 
              a snow-covered area at Ophir, Alaska.                                          0
   5091       The airplane was being operated as a visual flight rules (VFR) cross-country
              personal flight to McGrath, Alaska, when the accident occurred.                0
   5095       During a telephone conversation with the National Transportation Safety Board
              (NTSB) investigator-in-charge (IIC), on March 8, 2001, the pilot reported he
              landed near Ophir earlier in the day.
   5097       The pilot said he began a takeoff run toward the south, but the airplane 
              did not become airborne until it was within about 50 yards from several trees. 0
   5099       The airplane began a descending left turn toward the ground, and collided
              with several trees while the pilot was making an emergency landing.            0
   5100       The airplane received damage to the left main landing gear, the wings, 
              and the left stabilizer.                                                       0
iKnow> quit
Bye bye
 
SAMPLES>
Filter Sources
The following iKnow Shell example makes use of an existing domain named “mydomain” in the current namespace. The domain “mydomain” contains 100 sources. The use domain mydomain command specifies using “mydomain”, making it the current domain for the iKnow Shell. The list source command lists the first 10 sources in the current domain. The filter source 92 94 97 as myfilter command defines a filter named “myfilter” which filters out all sources except those specified by source Id. The use filter myfilter command establishes “myfilter” as the current filter. Now when the iKnow Shell issues a list source command, it applies “myfilter” and lists only the three sources specified in “myfilter”:
SAMPLES>DO $System.iKnow.Shell()
 
Welcome to the iKnow shell
Type '?' for help
Type 'quit' to exit
 
iKnow> use domain mydomain
Current domain: mydomain (1)
iKnow> list source
 srcId          externalId
   100    :SQL:Accident:96
    99    :SQL:Accident:98
    98    :SQL:Accident:94
    97   :SQL:Accident:100
    96    :SQL:Accident:80
    95    :SQL:Accident:99
    94    :SQL:Accident:95
    93    :SQL:Accident:88
    92    :SQL:Accident:97
    91    :SQL:Incident:90
iKnow> filter source 92 94 97 as myfilter
iKnow> use filter myfilter
Current filter: myfilter
 
iKnow> list source
 srcId          externalId
    97   :SQL:Accident:100
    94    :SQL:Accident:95
    92    :SQL:Accident:97
iKnow> quit
Bye bye
 
SAMPLES>
After a filter has been applied, a subsequent use filter filtername replaces the current filter with the new filter. To disable a filter, specify use filter 0.
iKnow Data Upgrade Utility
Each version of the iKnow data structures is assigned a system version number. Each iKnow domain is assigned a Version property value. All new domains are created with the same Version property as the current system version. Therefore, these two integer values are usually the same.
The following are the Caché versions, the corresponding iKnow system versions, and the principal changes to the indexing process:
Caché 2012.1 1 Initial iKnow indexing.
Caché 2012.2 2 Dominance and Proximity indexing added.
Caché 2013.1 3 Negation attribute indexing added.
Caché 2014.1 and 2015.1 4 Domain-independent dictionaries and blacklists.
Caché 2015.2 5 Stemming indexing added. Sentiment attribute indexing added.
You can use the GetCurrentSystemVersion() method of the %iKnow.Domain class to determine the iKnow data structures system version for the current Caché instance. You can use the GetAllDomains query to list all domains with their domain Version numbers, as shown in the Listing All Domains section of the “Setting Up the iKnow Environment” chapter.
If the iKnow data structures system version does not match the domain Version, these older iKnow domains cannot take advantage of the new iKnow features and performance improvements introduced with this new system version. Older domains will remain operational, but cannot take advantage of new iKnow data structure features until you upgrade the domain. Upgrading a domain increments its Version property. This upgrade operation requires the automatic re-indexing of the domain data. It does not require access to the original source texts. Each domain must be upgraded individually.
To upgrade a domain, use the UpgradeDomain() method of the %iKnow.Utils.UpgradeUtils class. Further details are provided in the InterSystems Class Reference documentation.
Note that the re-indexing that occurs when you upgrade a domain changes the domain Id, but does not change the domain name. Thus upgrading a domain may, in some cases, require changes to programs that reference the domain by a specific domain Id integer. For this reason, a domain should always be referenced by its Id property (or domain name). Coding practices that reference a domain by a literal integer Id value should be avoided.
Notes on Specific Version Upgrades
To Version 2
Upgrading a domain from iKnow data structures Version 1 to Version 2 substantially increases the space requirements for permanent and temporary globals. The space requirements for permanent globals increase from 8.7 times to 20 times the size of the original source texts. The space requirements for temporary globals increase from 10.7 times to 20 times the size of the original source texts. The space requirements for the cachetemp directory increase from 1.25 times to 4 times the size of the original source texts.
For this reason, you should only upgrade a large iKnow domain from iKnow data structures Version 1 to Version 2 if you have the available space and need the new iKnow data structure features (such as semantic dominance and semantic proximity).
To Version 4
Upgrading your system to Caché 2014.1 (or greater) automatically converts systemwide domain parameters. Systemwide domain parameters defined prior to Version 4 were truly system-wide (applying to all domains in all namespaces). Systemwide domain parameters at Version 4 and subsequent versions apply to all domains in the current namespace. Therefore, upgrading to Version 4 causes all existing systemwide domain parameters to be applied as namespace-wide domain parameters for all namespaces containing iKnow domains at the time of upgrade. Namespaces without iKnow domains, and subsequently created namespaces will not receive these systemwide domain parameter settings. Note that the SAMPLES namespace does not receive existing systemwide domain parameters, because upgrading your system overwrites SAMPLES, creating a namespace without iKnow domains.