Better documentation for solr-ruby

[Thiago Jackiw-2]

The 'out of the box' usage of solr-ruby and Solr 1.1/1.2 is a bit
frustrating. There are three different versions of the documentation
that explains you how to add a new document:

===============
Using the default installation of Solr 1.1 and solr-ruby

readme version:
conn.add(:id => 123, :title_text => 'Lucene in Action')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title_text'

wiki version:
conn.add(:id => 123, :title_t => 'Lucene in Action')
=> false

comment on connection.rb:
conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title'

So basically none of the options above were able to insert the
document in Solr 1.1


===============
Using the default installation of Solr 1.2 and solr-ruby

readme version:
conn.add(:id => 123, :title_text => 'Lucene in Action')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title_text'

wiki version:
conn.add(:id => 123, :title_t => 'Lucene in Action')
=> true

comment on connection.rb:
conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title'

Although the wiki version returned true, no records were found when
searching for 'action'

===============
Solr 1.1 using the schema.xml from solr-ruby/solr/conf

Solr wouldn't even start properly

===============
Solr 1.2 using the schema.xml from solr-ruby/solr/conf

readme version:
conn.add(:id => 123, :title_text => 'Lucene in Action')
=> true

wiki version:
conn.add(:id => 123, :title_t => 'Lucene in Action')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title_t'

comment on connection.rb:
conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field 'title'

The readme version worked as expected. So if this is really what users
have to do to get it going, shouldn't there be an explanation for it?

===============
Another thing, what's the reason for having two different versions of
schema.xml? The one under solr-ruby/solr/conf is different than the
one under solr-ruby/test/conf.

Also, is there a place other than digging through the unit tests to
see the options you can pass when adding a document or doing a search?

Sorry for the bunch of question guys, I'm test-driving it before I
implement acts_as_solr to use solr-ruby as the 'backend'.

--
Thiago Jackiw
acts_as_solr => http://acts-as-solr.railsfreaks.com

[Erik Hatcher]

Thiago,

You've hit on my weaknesses in getting this stuff as documented as it  
needs to be for consumption.  I personally use the unit tests as my  
documentation (we have near 100% code coverage, so it is  
comprehensive but short and sweet too).  RDoc has not been something  
I've gotten into, my apologies.  And I also apologize for the README  
and wiki from not being clear.

I run trunk Solr and trunk solr-ruby in most of my life, and right  
now they are both Solr 1.2 compatible, Solr 1.1 is not supported at  
all unless you went back in time with solr-ruby also.

The examples were never meant to work with the Solr example schema,  
but rather the Solr configuration that comes with solr-ruby (which is  
currently only in svn, not in the Ruby gem, my bad).  But, here's how  
I run it:

        java -Dsolr.solr.home=<path to solr-ruby's solr directory> -jar  
start.jar

Now the #add will work fine.  _text and _facet were the conventions I  
chose in solr-ruby examples, but solr-ruby is agnostic on the schema  
and any fields (that match the schema can be used).

My personal and professional life are in this summer time frenzy  
right now, so I won't be able to touch this stuff myself,  
conservatively, for the next couple of weeks, but I will be tuning in  
and committing patches if folks want to send 'em in, and by all means  
feel free to edit the wiki too.  RDoc patches in particular would  
really rock.  And we can find a way to publish them online either at  
RubyForge or as part of the Solr website.

        Erik



On Jun 16, 2007, at 12:55 AM, Thiago Jackiw wrote:

> The 'out of the box' usage of solr-ruby and Solr 1.1/1.2 is a bit
> frustrating. There are three different versions of the documentation
> that explains you how to add a new document:
>
> ===============
> Using the default installation of Solr 1.1 and solr-ruby
>
> readme version:
> conn.add(:id => 123, :title_text => 'Lucene in Action')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title_text'
>
> wiki version:
> conn.add(:id => 123, :title_t => 'Lucene in Action')
> => false
>
> comment on connection.rb:
> conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title'
>
> So basically none of the options above were able to insert the
> document in Solr 1.1
>
>
> ===============
> Using the default installation of Solr 1.2 and solr-ruby
>
> readme version:
> conn.add(:id => 123, :title_text => 'Lucene in Action')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title_text'
>
> wiki version:
> conn.add(:id => 123, :title_t => 'Lucene in Action')
> => true
>
> comment on connection.rb:
> conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title'
>
> Although the wiki version returned true, no records were found when
> searching for 'action'
>
> ===============
> Solr 1.1 using the schema.xml from solr-ruby/solr/conf
>
> Solr wouldn't even start properly
>
> ===============
> Solr 1.2 using the schema.xml from solr-ruby/solr/conf
>
> readme version:
> conn.add(:id => 123, :title_text => 'Lucene in Action')
> => true
>
> wiki version:
> conn.add(:id => 123, :title_t => 'Lucene in Action')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title_t'
>
> comment on connection.rb:
> conn.add(:id => 123, :title => 'Tlon, Uqbar, Orbis Tertius')
> SEVERE: org.apache.solr.core.SolrException: ERROR:unknown field  
> 'title'
>
> The readme version worked as expected. So if this is really what users
> have to do to get it going, shouldn't there be an explanation for it?
>
> ===============
> Another thing, what's the reason for having two different versions of
> schema.xml? The one under solr-ruby/solr/conf is different than the
> one under solr-ruby/test/conf.
>
> Also, is there a place other than digging through the unit tests to
> see the options you can pass when adding a document or doing a search?
>
> Sorry for the bunch of question guys, I'm test-driving it before I
> implement acts_as_solr to use solr-ruby as the 'backend'.
>
> --
> Thiago Jackiw
> acts_as_solr => http://acts-as-solr.railsfreaks.com

[Erik Hatcher]

On Jun 16, 2007, at 12:55 AM, Thiago Jackiw wrote:
> Another thing, what's the reason for having two different versions of
> schema.xml? The one under solr-ruby/solr/conf is different than the
> one under solr-ruby/test/conf.

No real reason other than to allow the tests to play with the schema  
a bit more if need-be.  The solr-ruby/solr/conf is the golden path  
schema for Flare at the moment, intentionally designed as simple as  
possible knowing that it does additional field type support like  
acts_as_solr.

> Also, is there a place other than digging through the unit tests to
> see the options you can pass when adding a document or doing a search?

Again, sadly, no not really.  The unit tests, I feel, are good enough  
to see the options, but certainly RDoc is the way to go for the details.

> Sorry for the bunch of question guys, I'm test-driving it before I
> implement acts_as_solr to use solr-ruby as the 'backend'.

Thanks Thiago!  I appreciate you coming over here to take a deeper  
look into solr-ruby.  I think you'll find it is a good fit for aas,  
but clearly not as well documented as we'd all like.

        Erik