There are multiple commit strategies in Solr. The most known is explicit <commit>s from the client. Then you have AutoCommit, configured in solrconfig.xml, which lets Solr automatically commit <add>s after a certain time or number of documents, and finally there may be a behind-the-scenes commit when the input buffer gets full.
What is it
CommitWithin is a commit strategy introduced in Solr 1.4, which lets the client ask Solr to make sure this <add> gets committed within a certain time. This leaves the control of when to do the commit to Solr itself, optimizing number of commits to a minimum while still fulfilling the update latency requirements. If I say <add commitWithin=10000> (in an XMLUpdateRequestHandler update), that tells Solr to make sure the document gets committed within 10000ms, i.e. 10s. I can then continue to add other documents within those 10 seconds (possibly with other commitWithin values), and Solr will automatically do a <commit> when the oldest <add> in the buffer is due.
Ways to do commitWithin
There are multiple ways to convey the commitWithin information to Solr.
In XML or JSON documents
You can specify a commitWithin parameter directly on the <add> tag, see UpdateXmlMessages for an example
In SolrJ you may optionally give a commitWithin value on the add() call, e.g. server.add(mySolrInputDocument, 10000); Solr3.5
In earlier versions you need to construct an AddUpdateCommand and then set the commitWithin attribute on that - a little more work. Example:
UpdateRequest req = new UpdateRequest(); req.add(mySolrInputDocument); req.setCommitWithin(10000); req.process(server);
Update Request parameter
All UpdateRequestHandlers support the commitWithin request parameter as of Solr3.4. This means that you may tell Solr to use a commitWithin value for the whole request. This is handy especially for CSVUpdateRequestHandler or ExtractingRequestHandler, which has no other way of conveying that information. An example using curl to push a PDF document, saying it should be committed within 10s:
curl "http://localhost:8983/solr/update/extract?literal.id=123&commitWithin=10000" -H "Content-Type: application/pdf" --data-binary @file.pdf