app.solr - Solr binding

This module provides a Gauche interface to Solr, an open source
search engine from Apache Lucene project.

   http://lucene.apache.org/solr/

We require Solr 3.1 or later.   This moduce accesses Solr via
its REST interface, so a Solr server process must be running.

Requires Gauche 0.9.1.


SYNOPSYS

  (use app.solr)

  (define *solr* (make <solr> :uri "http://localhost:8983/solr"))

  (solr-add *solr* '((id . 123)
                     (name . "Gauche manual")
                     (author . "Shiro Kawai")))

  (solr-commit *solr*)

  (solr-optimize *solr*)

  (define result-sxml
     (solr-query *solr* :query "author:Shiro Kawai"))
  (solr-response->result-count result-sxml)
  (solr-response->doc-sxml result-sxml)
  (solr-response->doc-nodes result-sxml)
  (solr-response->doc-alist result-sxml)

  (solr-delete *solr* :ids '(123 456)
                      :queries '("author:Shiro Kawai"))

  (solr-rollback *solr*)


DESCRIPTION

  <solr>

    A class to manage communication with a specific Solr server.
    You have to give a uri of the endpoint to :uri initial argument.
    APIs expect an instance of this class as the first argument.

  <solr-error>

    If Solr returns an error, APIs raises this condition.
    Those slots are filled:

    status - the response status, e.g. "500" for internal error etc.
    headers - parsed response headers.  you can retrieve fields by
              rfc822-header-ref (see rfc.822).
    body   - parsed response body, in SXML.

  solr-add solr doc :key (commit #f) (overwrite #t)

    Add a document.  DOC can be an alist ((field-name . field-value) ...)
    or any instance of <dictionary>.

    For the field value, Scheme real numbers, strings and symbols are
    converted to strings, and <date> objects (see srfi-19) are passed
    as ISO-8601 date string (after adjusted timezone to be zero).
    If field-value is a list, it is passed as a multivalue field.
    
    If the keyword argument commit is true, the change is committed
    before returning from this method.  Default is #f.

    If the keyword argument overwrite is true, a record with matching
    field declared as uniqueKey in the schema will be replaced by the
    passed record.  Default is #t.

  solr-add* solr docs :key (commit #f) (overwrite #t)

    Like solr-add, but you can pass a list of records.
    It is much more efficient than adding one record at a time.

  solr-commit solr :key (wait-flush #t) (wait-searcher #t)
                        (expunge-deletes #t)

    Commit the change.

  solr-optimize solr :key (wait-flush #t) (wait-searcher #t)
                          (max-segments 1)

    Tell Solr server to optimize intex files.  

  solr-rollback solr

    Rollback uncommitted changes.

  solr-delete solr :key (ids '()) (queries '()) (commit #f)

    Deletes records by matching ids (values of uniqueKey field) or
    queries.  Both can be specified at the same time.  If commit
    keyword argument is true, the deletes are committed before
    returning from this method.

  solr-query solr :key (query "*:*") (fields "*") (search-name "select")
                       (score #t) (sort #f) (params '())

    Searches document.   See the Solr document for the detailed syntax
    of query, fields and sort.
    If the schema defines alternativea search handlers, you can
    specify one by search-name argument.

    Returns SXML representation of the Solr response.  We provide
    several convenience procedures to extract typical information
    from the returned value; see below.

    PARAMS argument can be used to pass additional parameters.
    For example, the following call can retrieve "highlighting"
    section in which the hit word in description is highlighted:

    (solr-query solr :query "description:video"
                     :params '((hl #t) (hl.fl "description")))

    Or, the following call allow faceted search:

    (solr-query solr :query "*:*"
                     :params '((facet #t)
                               (facet.field "cat" "inStock")))

    Note that the highlighting information and faceted search
    results are returned in additional SXML nodes,
    rather than the list of <doc> nodes, so you need to extract
    the appropriate section.  For example, you can apply the
    following sxpath procedures to retrieve highlighting or
    faceted search results, respectively.

      (sxpath "//child::lst[attribute::name='highlighting']")
      (sxpath "//child::lst[attribute::name='facet_counts']")


  solr-response->result-count sxml

    Returns three values: The total number of hits of the query,
    the start count, and the number of records in this response.

    Solr pagenates the result.  By default, the result contains
    up to 10 documents; you can change it by passing 'rows' parameter.
    The following example asks 20 documents at at time, and
    supposes that there are actually 34 matched documents.

      (let1 r (solr-query solr :query "foo:bar"
                               :params '((rows 20)))
        (solr-response->result-count r)
      ;=> 34, 0 and 20, for example.

    To extract the rest of the result, you pass 'start' parameter.

      (let1 r (solr-query solr :query "foo:bar"
                               :params '((rows 20) (start 20)))
        (solr-response->result-count r)
      ;=> 34, 20 and 14, for example.


  solr-response->doc-nodes sxml

    Returns the list of <doc> nodes in the result SXML.


  solr-response->doc-alist sxml

    Returns the list of documents, each converted to alist from
    <doc> sxml node.