You are viewing a plain text version of this content. The canonical link for it is here.
Posted to solr-commits@lucene.apache.org by Apache Wiki <wi...@apache.org> on 2009/08/10 04:48:03 UTC
[Solr Wiki] Update of "SolrpyDoc" by BrianTingle
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Solr Wiki" for change notification.
The following page has been changed by BrianTingle:
http://wiki.apache.org/solr/SolrpyDoc
The comment on the change is:
documentation from http://code.google.com/p/solrpy/source/browse/trunk/solr/core
New page:
solrpy 0.7
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
Re: [Solr Wiki] Update of "SolrpyDoc" by BrianTingle
Posted by Chris Hostetter <ho...@fucit.org>.
: The following page has been changed by BrianTingle:
: http://wiki.apache.org/solr/SolrpyDoc
:
: The comment on the change is:
: documentation from http://code.google.com/p/solrpy/source/browse/trunk/solr/core
:
: New page:
: solrpy 0.7
Uh... this is odd, it's a direct copy of the python docs included in
solrpy...
http://code.google.com/p/solrpy/source/browse/trunk/solr/core.py
...it doesn't seem appropriate to be cutting/pasting verbatim on the Solr
wiki (especially since it's going going to get out of sync overtype).
Shouldn't we just be providing a link to this client project? maybe
with a short syntax example?
-Hoss