Differences between revisions 1 and 2
Revision 1 as of 2009-08-10 02:47:59
Size: 10000
Editor: adsl-69-107-97-40
Comment: documentation from http://code.google.com/p/solrpy/source/browse/trunk/solr/core
Revision 2 as of 2009-08-18 23:07:37
Size: 286
Editor: HossMan
Comment: remove cut/paste content taken from other site, replace with links
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
solrpy 0.7 [http://code.google.com/p/solrpy/ Solrpy] is a python client for Solr.
Line 3: Line 3:
A simple client to the solr search service for python.

Features
--------
 * Supports SOLR 1.2+
 * Supports http/https and SSL client-side certificates
 * Uses persistent HTTP connections by default
 * Properly converts to/from SOLR data types, including datetime objects
 * Supports both querying and update commands (add, delete).
 * Supports batching of commands
 * Requires Python 2.3+
 * Django-like Paginator for a solr response object
 * Test cases for the Python Solr client


Connections
-----------
`SolrConnection` can be passed in the following parameters.
Only `url` is required,.

    url -- URI pointing to the SOLR instance. Examples:

        http://localhost:8080/solr
        https://solr-server/solr

        Your python install must be compiled with SSL support for the
        https:// schemes to work. (Most pre-packaged pythons are.)

    persistent -- Keep a persistent HTTP connection open.
        Defaults to true.

    timeout -- Timeout, in seconds, for the server to response.
        By default, use the python default timeout (of none?)
        NOTE: This changes the python-wide timeout.

    ssl_key, ssl_cert -- If using client-side key files for
        SSL authentication, these should be, respectively,
        your PEM key file and certificate file

Once created, a connection object has the following public methods:

    query (q, fields=None, highlight=None,
           score=True, sort=None, **params)

            q -- the query string.

            fields -- optional list of fields to include. It can be either
                a string in the format that SOLR expects ('id,f1,f2'), or
                a python list/tuple of field names. Defaults to returning
                all fields. ("*")

            score -- boolean indicating whether "score" should be included
                in the field list. Note that if you explicitly list
                "score" in your fields value, then this parameter is
                effectively ignored. Defaults to true.

            highlight -- indicates whether highlighting should be included.
                `highlight` can either be `False`, indicating "No" (the
                default), `True`, incidating to highlight any fields
                included in "fields", or a list of field names.

            sort -- list of fields to sort by.

            Any parameters available to SOLR 'select' calls can also be
            passed in as named parameters (e.g., fq='...', rows=20, etc).

            Many SOLR parameters are in a dotted notation (e.g.,
            `hl.simple.post`). For such parameters, replace the dots with
            underscores when calling this method. (e.g.,
            hl_simple_post='</pre'>)

            Returns a Response object

    add(**params)

            Add a document. Pass in all document fields as
            keyword parameters:

                add(id='foo', notes='bar')

            You must "commit" for the addition to be saved.
            This command honors begin_batch/end_batch.

    add_many(lst)

            Add a series of documents at once. Pass in a list of
            dictionaries, where each dictionary is a mapping of document
            fields:

                add_many( [ {'id': 'foo1', 'notes': 'foo'},
                            {'id': 'foo2', 'notes': 'w00t'} ] )

            You must "commit" for the addition to be saved.
            This command honors begin_batch/end_batch.

    delete(id)

            Delete a document by id.

            You must "commit" for the deletion to be saved.
            This command honors begin_batch/end_batch.

    delete_many(lst)

            Delete a series of documents. Pass in a list of ids.

            You must "commit" for the deletion to be saved.
            This command honors begin_batch/end_batch.

    delete_query(query)

            Delete any documents returned by issuing a query.

            You must "commit" for the deletion to be saved.
            This command honors begin_batch/end_batch.


    commit(wait_flush=True, wait_searcher=True)

            Issue a commit command.

            This command honors begin_batch/end_batch.

    optimize(wait_flush=True, wait_searcher=True)

            Issue an optimize command.

            This command honors begin_batch/end_batch.

    begin_batch()

            Begin "batch" mode, in which all commands to be sent
            to the SOLR server are queued up and sent all at once.

            No update commands will be sent to the backend server
            until end_batch() is called. Not that "query" commands
            are not batched.

            begin_batch/end_batch transactions can be nested.
            The transaction will not be sent to the backend server
            until as many end_batch() calls have been made as
            begin_batch()s.

            Batching is completely optional. Any update commands
            issued outside of a begin_batch()/end_batch() pair will
            be immediately processed.

    end_batch(commit=False)

            End a batching pair. Any pending commands are sent
            to the backend server. If "True" is passed in to
            end_batch, a <commit> is also sent.

    raw_query(**params)

            Send a query command (unprocessed by this library) to
            the SOLR server. The resulting text is returned un-parsed.

                raw_query(q='id:1', wt='python', indent='on')

            Many SOLR parameters are in a dotted notation (e.g.,
            `hl.simple.post`). For such parameters, replace the dots with
            underscores when calling this method. (e.g.,
            hl_simple_post='</pre'>)

    close()
            Close the underlying HTTP(S) connection.


Query Responses
---------------

    Calls to connection.query() return a Response object.

    Response objects always have the following properties:

        results -- A list of matching documents. Each document will be a
            dict of field values.

        results.start -- An integer indicating the starting # of documents

        results.numFound -- An integer indicating the total # of matches.

        results.maxScore -- An integer indicating the maximum score assigned
                            to a document. Takes into account all of documents
                            found by the query, not only the current batch.

        header -- A dict containing any responseHeaders. Usually:

            header['params'] -- dictionary of original parameters used to
                        create this response set.

            header['QTime'] -- time spent on the query

            header['status'] -- status code.

            See SOLR documentation for other/typical return values.
            This may be settable at the SOLR-level in your config files.


        next_batch() -- If only a partial set of matches were returned
            (by default, 10 documents at a time), then calling
            .next_batch() will return a new Response object containing
            the next set of matching documents. Returns None if no
            more matches.

            This works by re-issuing the same query to the backend server,
            with a new 'start' value.

        previous_batch() -- Same as next_batch, but return the previous
            set of matches. Returns None if this is the first batch.

    Response objects also support __len__ and iteration. So, the following
    shortcuts work:

        responses = connection.query('q=foo')
        print len(responses)
        for document in responses:
            print document['id'], document['score']


    If you pass in `highlight` to the SolrConnection.query call,
    then the response object will also have a "highlighting" property,
    which will be a dictionary.


Quick examples on use:
----------------------

Example showing basic connection/transactions

    >>> from solr import *

    >>> c = SolrConnection('http://localhost:8983/solr')

    >>> c.add(id='500', name='python test doc', inStock=True)

    >>> c.delete('123')

    >>> c.commit()


Examples showing the search wrapper

    >>> response = c.query('test', rows=20)

    >>> print response.results.start
     0
    >>> for match in response:
    ... print match['id'],
      0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
    >>> response = response.next_batch()
    >>> print response.results.start
     20

Add 3 documents and delete 1, but send all of them as a single transaction.

    >>> c.begin_batch()

    >>> c.add(id="1")

    >>> c.add(id="2")

    >>> c.add(id="3")

    >>> c.delete(id="0")

    >>> c.end_batch(True)

Enter a raw query, without processing the returned HTML contents.

    >>> print c.raw_query(q='id:[* TO *]', wt='python', rows='10')


SolrPaginator
----------------------
    
    Create a Django-like Paginator for a solr response object. Can be handy
    when you want to hand off a Paginator and/or Page to a template to
    display results, and provide links to next page, etc.

    For example:
    >>> from solr import SolrConnection, SolrPaginator

    >>>

    >>> conn = SolrConnection('http://localhost:8083/solr')

    >>> response = conn.query('title:huckleberry')

    >>> paginator = SolrPaginator(response)

    >>> print paginator.num_pages

    >>> page = paginator.get_page(5)

    For more details see the Django Paginator documentation and solrpy
    unittests.

      http://docs.djangoproject.com/en/dev/topics/pagination/


source: http://code.google.com/p/solrpy/source/browse/trunk/solr/core.py

source: http://code.google.com/p/solrpy/source/browse/trunk/solr/paginator.py
 * Home Page: http://code.google.com/p/solrpy/
 * Subversion repo: http://solrpy.googlecode.com/svn/
 * !PyPi Listing: http://pypi.python.org/pypi/solrpy/
 * Discussion: http://groups.google.com/group/solrpy

SolrpyDoc (last edited 2009-09-20 22:05:18 by localhost)