Swish-E Logo


SWISH-RUN - Running Swish and Command Line Switches


Table of Contents:

[ TOC ]

OVERVIEW

The SWISH-E program is controlled by command line arguments (called switches). Often, SWISH-E is run manually from a shell (command prompt), or from a program such as a CGI script that passes the command line arguments to swish.

Note: A number of the command line switches may be specified in the SWISH-E configuration file specified with the -c command line argument. Please see SWISH-CONFIG for a complete description of available configuration file directives.

There are two basic operating modes of SWISH-E: indexing and searching. There are command line arguments that are unique to each mode, and others that apply to both (yet may have different meaning depending on the operating mode). These command line arguments are listed below, grouped by:

INDEXING -- describes the command line arguments used while indexing.

SEARCHING -- lists the command line arguments used while searching.

OTHER SWITCHES -- lists switches that don't apply to searching or indexing.

Beginning with SWISH-E version 2.1, you may embed the SWISH-E search engine into your applications. Please see SWISH-LIBRARY.

[ TOC ]


INDEXING

Swish indexing is initiated by passing command line arguments to swish. The command line arguments used for searching are described in SEARCHING. Also, see SWISH-SEARCH for examples of searching with SWISH-E.

SWISH-E usage:

 
    swish-e [-i dir file ... ] [-c file] [-f file] [-l] \
            [-v (num)] [-S method(fs|http|prog)] [-N path]

The -h switch (help) will list the available SWISH-E command line arguments:

 
    swish-e -h

Typically, most if not all indexing settings are placed in a configuration file (specified with the -c switch). Once the configuration file is setup indexing is initiated as:

 
    swish-e -c /path/to/config/file

See SWISH-CONFIG for information on the configuration file.

Security Note: If the swish binary is named swish-search then swish will not allow any operation that would cause swish to write to the index file.

When indexing it may be advisable to index to a temporary file, and then after indexing has successfully completed rename the file to the final location. This is especially important when replacing an index that is currently in use.

 
    swish-e -c swish.config -f index.tmp
    [check return code from swish or look for err: output]
    mv index.tmp index.swish-e

[ TOC ]


Indexing Command Line Arguments

-i *directories and/or files* (input file)

This specifies the directories and/or files to index. Directories will be indexed recursively. This is typically specified in the configuration file with the IndexDir directive instead of on the command line. Use of this switch overrides the configuration file settings.

-S [fs|http|prog] (document source/access mode)

This specifies the method to use for accessing documents to index. Can be either fs for local indexing via the file system (the default), http for spidering, or prog for reading documents from an external program.

Located in the conf directory are example configuration files that demonstrate indexing with the different document source methods.

See the SWISH-FAQ for a discussion on the different indexing methods, and the difference between spidering with the http method vs. using the file system method.

fs - file system

The fs method simply reads files from a local (or networked) drive. This is the most common and fastest way to index documents with Swish. See SWISH-CONFIG for configuration directives specific to the fs method.

http - spider a web server

The http method is used to spider web servers. It uses an included helper program called swishspider located in the src directory. Swish needs to be able to locate this program when using the http method. See SWISH-CONFIG for configuration directives specific to the http method.

prog - general purpose access method

The prog method is new to SWISH-E version 2.2. It's designed as a general purpose method to feed documents to swish from an external program. For example, the program can read a database (e.g. MySQL), spider a web server, or convert documents from one format to another (e.g. pdf to html). Or, you can simply use it to read the files of the file system (like -S fs), yet provide you with full control of what files are indexed.

The external program name to run is passed to swish either by the IndexDir directive, or via the -i option. Additional parameters may be passed to the external program via the SwishProgParameters directive.

The external program prints to standard output (which swish captures) a set of headers followed by the content of the file to index. The output looks similar to an email message or a HTTP document returned by a web server in that it includes a name/value pair headers, a blank line, and the content. The content length is determined by a content-length header supplied to swish by the program; there is no ``end of record'' character or flag sent between documents.

Here's a simple example written in Perl:

 
    #!/usr/local/bin/perl -w
    use strict;
    
    # Build a document
    my $doc = <<EOF;
    <html>
    <head>
        <title>Document Title</title>
    </head>
        <body>
            This is the text.
        </body>
    </html>
    EOF
    
    
    # Prepare the headers for swish
    my $path = 'Example.file';
    my $size = length $doc;
    my $mtime = time;
    
    # Output the document (to swish)
    print <<EOF;
    Path-Name: $path
    Content-Length: $size
    Last-Mtime: $mtime
    Document-Type: HTML
    
    EOF
    
        print $doc;

The external program must pass to swish the Path-Name: and Content-Length: headers. The optional Last-Mtime: parameter is the last modification time of the file, and must be a time stamp (seconds since the epoch on your platform). You may override swish's determination of document type (Indexcontents) by using the Document-Type: header.

The above program only returns one document and exits, which is not very useful. Normally, your program would read data from some source, such as files or a database, format as XML, HTML, or text, and pass them to swish, one after another. The Content-Length: header tells swish where each document ends -- there is not any special ``end of record'' character or marker.

To index with the above example you need to make sure that the program is executable (and that the path to perl is correct), and then call swish telling to run in prog mode, and the name of the program to use for input.

 
    % chmod 755 example.pl
    % ./swish-e -S prog -i example.pl

 
    
A few more useful example programs are provided in the swish-e distribution
located in the F<prog-bin> directory.

The prog method bypasses some of the configuration parameters available to the file system method -- settings such as IndexDir and FileRules are ignored when using the prog method. It's expected that these operations are better accomplished in the external program before passing the document onto swish. In other words, when using the prog method, only send the documents to swish that you want indexed.

You may use swish's filter feature with the prog method, but performance will be better if you run filtering programs from within your external program.

Notes when using -S prog on MS Windows

When using swish-e on Windows, you must use the DOS-style backslash to separate the path segments. This is required because swish runs the external program with popen() which uses the shell to run the program and the DOS shell requires a backslash as the path separator.

 
    swish-e -S prog -i e:\progra~1\swish-e\prog.exe

In the configuration file you will need doube-backslashes:

 
    Indexdir c:\\path\\to\\program.exe

Currently, you *cannot* use spaces in the pathname:

 
    IndexDir '"E:\\Program Files\\swish-e\\prog.exe"'  ** does not work! **

This is because swish does some checks on the file name before running the program, and the double-quotes within the file name will cause these checks to fail. This may change in the future.

Windows does not use the shebang (#!) line of a program to determine the program to run. So, when running, for example, a perl program you will need to specify the perl.exe binary as the program, and use the SwishProgParameters to name the file.

 
    IndexDir e:\\perl\\bin\\perl.exe
    SwishProgParameters read_database.pl
    

-f *indexfile* (index file)

If you are indexing, this specifies the file to save the generated index in, and you can only specify one file. See also IndexFile in the configuration file.

If you are searching, this specifies the index files (one or more) to search from. The default index file is index.swish-e in the current directory.

-c *file ...* (configuration files)

Specify the configuration file(s) to use for indexing. This file contains many directives that control how SWISH-E proceeds. See SWISH-CONFIG for a complete listing of configuration file directives.

Example:

 
    swish-e -c docs.conf

If you specify a directory to index, an index file, or the verbose option on the command-line, these values will override any specified in the configuration file.

You can specify multiple configuration files. For example, you may have one configuration file that has common site-wide settings, and another for a specific index.

Examples:

 
    1) swish-e -c swish-e.conf
    2) swish-e -i /usr/local/www -f index.swish-e -v -c swish-e.conf
    3) swish-e -c swish-e.conf stopwords.conf

  1. The settings in the configuration file will be used to index a site.

  2. These command-line options will override anything in the configuration file.

  3. The variables in swish-e.conf will be read, then the variable in stopwords.conf will be read. Note that if the same variables occur in both files, older values may be written over.

-e (economy mode)

For large sites indexing may require more RAM than is available. The -e switch tells swish to use disk space to store data structures while indexing, saving memory. This option is recommended if swish uses so much RAM that the computer begins to swap excessively, and you cannot increase available memory. The trade-off is longer indexing times, and a busy disk drive.

-l (symbolic links)

Specifying this option tells swish to follow symbolic links when indexing. The configuration file value FollowSymLinks will override the command-line value.

The default is not to follow symlinks. A small improvement in indexing time my result from enabling FollowSymLinks since swish does not need to stat every directory and file processed to determine if it is a symbolic link.

-N path (index only newer files)

The -N option takes a path to a file, and only files newer than the specified file will be indexed. This is helpful for creating incremental indexes -- that is, indexes that contain just files added since the last full index was created of all files.

Example (bad example)

 
    swish-e -c config.file -N index.swish-e -f index.new
   
This will index as normal, but only files with a modified date newer
than F<index.swish-e> will be indexed.

This is a bad example because it uses index.swish-e which one might assume was the date of last indexing. The problem is that files might have been added between the time indexing read the directory and when the index.swish-e file was created -- which can be quite a bit of time for very large indexing jobs.

The only solution is to prevent any new file additions while full indexing is running. If this is impossible then it will be slightly better to do this:

Full indexing:

 
    touch indexing_time.file
    swish-e -c config.file -f index.tmp
    mv index.tmp index.full

Incremental indexing:

 
    swish-e -c config.file -N indexing_time.file -f index.tmp
    mv index.tmp index.incremental

Then search with

 
    swish-e -w foo -f index.full index.incremental

or merge the indexes

 
    swish-e -M index.full index.incremental index.tmp
    mv index.tmp index.swish-e
    swish-e -w foo

-v [0|1|2|3|4] (verbosity level)

The -v option can take a numerical value from 0 to 4. Specify 0 for completely silent operation and 3 for detailed reports. A level of 4 and above is used to generate mostly debugging output. If no value is given then 3 is assumed. See also IndexReport in the configuration file.

[ TOC ]


SEARCHING

The following command line arguments are available when searching with SWISH-E. These switches are used to select the index to search, what fields to search, and how and what to print as results.

This section just lists the available command line arguments and their usage. Please see SWISH-SEARCH for detailed searching instructions.

Warning: If using SWISH-E via a CGI interface, please see CGI Danger!

Security Note: If the swish binary is named swish-search then swish will not allow any operation that would cause swish to write to the index file.

[ TOC ]


Searching Command Line Arguments

-w *word1 word2 ...* (query words)

This performs a case-insensitive search using a number of keywords. If no index file to search is specified (via the -f switch), swish-e will try to search a file called index.swish-e in the current directory.

 
    swish-e -w word

Phrase searching is accomplished by placing the quote delimiter (a double-quote by default) around the search phrase.

 
    swish-e -w 'word or "this phrase"'

Search would should be protected from the shell by quotes. Typically, this is single quotes when running under Unix.

Under Windows command.com you may not need to use quotes, but you will need to backslash the quotes used to delimit phrases:

 
    swish-e -w \"a phrase\"

The phrase delimiter can be set with the -P switch.

The search may be limited to a MetaName. For example:

 
    swish-e -w meta1=(foo or baz)

will only search within the meta1 tag.

Please see SWISH-SEARCH for a description of MetaNames.

-f *file1 file2 ...* (index files)

Specifies the index file(s) used while searching. More than one file may be listed, and each file will be searched. If no -f switch is specified then the file index.swish-e in the current directory will be used as the index file.

-m *number* (max results)

While searching, this specifies the maximum number of results to return. The default is to return all results.

This switch is often used in conjunction with the -b switch to return results one page at a time (strongly recommended for large indexes).

-b *number* (beginning result)

Sets the begining search result to return (records are numbered from 1). This switch can be used with the -m switch to return results in groups or pages.

Example:

 
    swish-e -w 'word' -b 1 -m 20    # first 'page'
    swish-e -w 'word' -b 21 -m 20   # second 'page'

-t HBthec (context searching)

The -t option allows you to search for words that exist only in specific HTML tags. Each character in the string you specify in the argument to this option represents a different tag in which to search for the word. H means all HEAD tags, B stands for BODY tags, t is all TITLE tags, h is H1 to H6 (header) tags, e is emphasized tags (this may be B, I, EM, or STRONG), and c is HTML comment tags

search only in header (<H*>) tags

 
    swish-c -w word -t h

-d *string* (delimiter)

Set the delimiter used when printing results. By default, SWISH-E separates the output fields by a space, and places double-quotes around the document title. This output may be hard to parse, so it is recommended to use -d to specify a character or string used as a separator between fields.

The string dq means ``double-quotes''.

 
    swish-e -w word -d ,    # single char
    swish-e -w word -d ::   # string
    swish-e -w word -d '"'  # double quotes under Unix
    swish-e -w word -d \"   # double quotes under Windows
    swish-e -w word -d dq   # double quotes

The following control characters may also be specified: \t \r \n \f.

-P *character*

Sets the delimiter used for phrase searches. The default is double quotes ".

Some examples under bash: (be careful about you shell metacharacters)

 
    swish-e -P ^ -w 'title=^words in a phrase^'
    swish-e -P \' -w "title='words in a pharse"'

-p *property1 property2 ...* (display properties)

This causes swish to print the listed property in the search results. The properties are returned in the order they are listed in the -p argument.

Properties are defined by the ProperNames directive in the configuration file (see SWISH-CONFIG) and properties must also be defined in MetaNames. Swish stores the text of the meta name as a property, and then will return this text while searching if this option is used.

This feature is very useful for returning data included in a source documnet without having to re-read the source document while searching. For example, this could be used to return a short document description. See also see Document Summeries in SWISH-CONFIG.

To return the subject and category properties while indexing.

 
    swish-e -w word -p subject category

NOTE: it is necessary to have indexed with the proper PropertyNames directive in the user config file in order to use this option.

-s *property [asc|desc] ...* (sort)

Normally, search results are printed out in order of relevancy, with the most relevant listed first. The -s sort switch allows you to sort results in order of a specified property, where a property was defined using the MetaNames and PropertyNames directives during indexing (see SWISH-CONFIG).

The string passed can include the strings asc and desc to specify the sort order, and more than one property may be specified to sort on more than one key.

Examples:

sort by title property ascending order

 
    -s title

sort descending by title, ascending by name

 
    -s title desc name asc

-L limit to a range of property values (Limit)

This is an experimental feature!

The -L switch can be used to limit search results to a range of properties (properties are defined with the PropertyNames* family of directives). Properties must be presorted for this feature to work. (Presorted properties is the default swish behavior.) This feature will not work with swishrank or swishdbfile properties.

Example:

 
    swish-e -w foo -L swishtitle a m

finds all documents that contain the word foo, and where the document's title is in the range of a to m, inclusive. Limiting may be done with user-defined properties, as well.

For example, if you indexed documents that contain a created timestamp in a meta tag:

 
    <meta name="created_on" content="982648324">

Then you tell Swish that you have a property called created_on, and that it's a timestamp.

 
    PropertyNamesDate created_on

After indexing you will be able to limit documents to a range of timestamps:

 
    -w foo -L created_on  946684800 949363199

will find documents containing the word foo and that have a created_on date from the start of Jan 1, 2000 to the end of Jan 31, 2000.

Note: swish currently does not parse dates; Unix timestamps must be used.

Two special formats can be used:

 
    -L swishtitle <= m
    -L swishtitle >= m

Finds titles less than or equal, or grater than or equal to the letter m. Case is ignored when comparing strings.

This is an experimental feature, and its use and interface are subject to change.

-x formatstring (extended output format)

The -x switch defines the output format string. The format string can contain plain text and property names (including swish-defined internal property names) and is used to generate the output for every result. In addition, the output format of the property name can be controlled with C-like printf format strings. This feature overrides the cmdline switches -d and -p, and a warning will be generated if -d or -p are used with -x.

For example, to return just the title, one per line, in the search results:

 
    swish-e  -w ...   -x '<swishtitle>\n' ...

Note: the \n may need to be protected from your shell.

See also the ResultExtFormatName in SWISH-CONFIG for a way to define named format strings in the swish configuration file.

Format of "formatstring":

 
    "text<propertyname>text<propertyname fmt=propfmtstr>text..."

Where propertyname is:

propertynames must be placed within ``<'' and ``>''.

User properties:

SWISH-E allows you to specify certain META tags within your documents that can be used as document properties. The contents of any META tag that has been identified as a document property can be returned as part of the search results. Doucment properties must be defined while indexing using the PropertyNames configuration directive (see SWISH-CONFIG).

Examples of user-defined PropertyNames:

 
    <keywords>
    <author>
    <deliveredby>
    <reference>
    <id>

Note: In swish-e 2.2 all user properties are String type. This may change in future...

Auto properties:

Swish defines a number of ``Auto'' properties for each document indexed. These are available for output when using the -x format.

 
    Name               Type     Contents
    swishreccount      Integer  Result record counter
    swishtitle         String   Document title (html only)
    swishrank          Integer  Result rank for this hit
    swishdocpath       String   URL or filepath to document
    swishdocsize       Integer  Document size in bytes
    swishlastmodified  Date     Last mod. date of document
    swishdescription   String   Description of document (see:StoreDescription)
    swishstartpos      Integer  [not yet used]
    swishdbfile        String   Path of swish database indexfile

The Auto properties can also be specified using shortcuts:

 
    %c     = <swishreccount>        (c-ount)
    %d     = <swishdescription>
    %D     = <swishlastmodified>    (D-ate)
    %I     = <swishdbfile>          (I-ndex)
    %p     = <swishdocpath>         (P-ath)
    %r     = <swishrank>
    %l     = <swishdocsize>         (lentgh)
    %S     = <swishstartpos>
    %t     = <swishtitle>
    %%     = %

Formatstrings of properties:

Properties listed in an -x format string can include format control strings. These ``propertyformats'' are used to control how the contents of the associated property are printed. Property formats are used like C-language printf formats. The property format is specified by including the attribute ``fmt'' within the property tag.

General syntax:

 
    -x '<propertyname fmt="propfmtstr">'

where subfmt controls the output format of propertyname.

Examples of property format strings:

 
        date type:    ...fmt='%d.%m.%Y'
        string type:  ...fmt='%-40.20s'
        integer type: ...fmt=/%8.8d/

Please see the manual pages for strftime(3) and sprintf(3) for an explanation of format strings.

The first character of a property format string defines the delimiter for this format string. For example,

 
    swish -x  "<author  fmt=\"%20s\"> ...\n"
    swish -x  "<author  fmt='%20s'> ...\n"
    swish -x  "<author  fmt=/%20s/> ...\n"

Standard predefined formats:

If you ommit the sub-format, the following formats are used:

 
    String type:       "%s"  (like printf char *)
    Integer type:      "%d"  (like printf int)
    Float type:        "%f"  (like printf double) 
    Date type:         "%Y-%m-%d %H:%M:%S" (like strftime)
                        special: fixed format string "%ld" = print seconds since epoch
                                   

Text in "formatstring" or "propfmtstr":

Text will be output as-is in format strings (and property format strings). Special characters can be escaped with a backslash. To get a new line for each result hit, you have to include the Newline-Character ``\n'' at the end of ``fmtstr''.

 
    -x "<swishreccount>|<swishrank>|<swishdocpath>\n"
    -x "Count=<swishreccount>, Rank=<swishrank>\n"
    -x "\<p\>Title=\<b\><swishtitle>\<p\>"
    -x 'Date: <swishlastmodified fmt="%m/%d/%Y">\n'
    -x 'Date in seconds: <swishlastmodified fmt=/%ld/>\n'

Control/Escape charcters:

you can use C-like control escapes in the format string:

 
   known controls:      \a, \b, \f, \n, \r, \t, \v,
   digit escapes:       \xhexdigits   \0octaldigits
   character escapes:   \anychar  

Example,

 
    swish -x "%c\t%r\t%p\t\"<swishtitle fmt=/%40s/>\"\n"

Examples of -x format strings:

 
    -x "%c|%r|%p|%t|%D|%d\n"
    -x "%c|%r|%p|%t|<swishdate fmt=/%A, %d. %B %Y/>|%d\n"
    -x "<swishrank>\t<swishdocpath>\t<swishtitle>\t<keywords>\n
    -x "xml_out: \<title\><swishtitle>\>\</title\>\n"
    -x "xml_out: <swishtitle fmt='<title>%s</title>'>\n"

-H [0|1|2|3|<n>] (header output verbosity)

The -H n switch generates extened header output. This is most useful when searching more than one index file at a time, either by specifying more than one index file with the -f switch, or when searching a merged index file. In these cases, -H 2 will generate a set of headers specific to each index file. This gives access to the settings used to generate each index file.

Even when searching a single index file, -H n will provided additional information about the index file, how it was indexed, and how swish is interperting the query.

 
    -H 0 : print no header information, output only search result entries.
    -H 1 : print standard result header (default).
    -H 2 : print additional header information for each searched index file.
    -H 3 : enhanced header output (e.g. print stopwords).
    -H 9 : print diagnostic information in the header of the results (changed from: C<-v 4>)

[ TOC ]


OTHER SWITCHES

-V (version)

Print the current version.

-k *letter* (print out keywords)

The -k switch is used for testing and will cause swish to print out all keywords in the index beginning with that letter. You may enter -k '*' to generate a list of all words indexed by swish.

-D *index file* (debug index)

The -D option is no longer supported in version 2.2.

-T *options* (trace/debug swish)

The -T option is used to print out information that may be helpful when debugging swish-e's operation. This option replaced the -D option of previous versions.

Running -T help will print out a list of available *options*

[ TOC ]


Merging Index Files

At times it can be useful to merge different index files into one file for searching. This could be because you want to keep separate site indexes and a common one for a global search, or because your site is very large and Swish-e runs out of memory if you try to index it directly.

You should merge only indexes that were indexed with common settings. Otherwise results may be confusing (e.g. don't mix stemming and non-stemming indexes, or indexes with different WordCharacter settings).

 
  usage: swish-e [-v (num)] [-c file] -M index1 index2 ... outputfile

Due to the structure of the swish-e index, merging may or may not require less memory than indexing all files at one time.

-M *file file ...* (merge)

This allows you to merge two or more index files - the last file you specify on the list will be the output file.

Merging removes all redundant file and word data. To estimate how much memory the operation will need, sum up the sizes of the files to be merged and divide by two. That's about the maximum amount of memory that will be used.

You can use the -v option to produce feedback while merging and the -c option with a configuration file to include new administrative information in the new index file.

-c *configuration file*

Specify a configuration file while indexing to add administrative information to the output index file.

[ TOC ]


Document Info

$Id: SWISH-RUN.pod,v 1.16 2001/12/30 17:53:44 whmoseley Exp $

. [ TOC ]