Aaron has posted 2 posts at DZone. View Full User Profile

How to implement row level access control in Lucene

  • submit to reddit
Below I have written some fully functionally code that shows how you could implement row level access control in Lucene (2.3.2). Basically you have to index enough information to be able to search (in a single query) and find all documents that a given user has access to read.

In the below example there are two fields:

DATA: Which contains any data that you want your users to be able to search. NOTE: You can have as many data fields as you like.

ACL_FIELD: The field used to determine what users have access to this document. Note: You can have as many access control fields as you like.

All you have to do is built the access control query for each user and submit your user's query unchanged.
public class TestIndexerSearcher {

public static void main(String[] args) throws Exception {
Directory directory = new RAMDirectory();
IndexWriter indexWriter = new IndexWriter(directory, new StandardAnalyzer());

IndexSearcher indexSearcher = new IndexSearcher(directory);

QueryParser parser = new QueryParser("DATA", new StandardAnalyzer());
Query query = parser.parse("sametoken");

//This is all you have to add to your existing code.
Filter aclFilter = applyAccessControl(new TermQuery(
new Term("ACL_FIELD","access")));

Hits hits = indexSearcher.search(query, aclFilter);
System.out.println("Hits[" + hits.length() + "]");
for (int i = 0; i < hits.length(); i++) {
Document doc = hits.doc(i);
System.out.println("DATA [" + doc.get("DATA") +
"] ACL_FIELD [" + doc.get("ACL_FIELD") + "]");

private static Filter applyAccessControl(Query aclQuery) {
return new CachedQueryFilter(aclQuery.toString(),
new QueryWrapperFilter(aclQuery));

private static Document buildDocument(String... fieldInfo) {
Document document = new Document();
for (int i = 0; i < fieldInfo.length; i++) {
String[] split = fieldInfo[i].split(":");
String fieldName = split[0];
String fieldValue = split[1];
document.add(new Field(fieldName,fieldValue,
return document;

After you run this code, you will get a single hit, not the two that you would normally get if the access control filter wasn't in place.
public class CachedQueryFilter extends Filter {
private static final long serialVersionUID = 6797293376134753695L;
private Filter filter;
private String key;
private static transient Map<String, BitSetCache> filterCache =
new ConcurrentHashMap<String, BitSetCache>();

public CachedQueryFilter(String key, Filter filter) {
this.filter = filter;
this.key = key;

public BitSet bits(IndexReader reader) throws IOException {
BitSetCache cachedBitSet = (BitSetCache) filterCache.get(key);
if (cachedBitSet != null) {
BitSet bitSet = cachedBitSet.bitSet.get();
if (bitSet != null && cachedBitSet.indexReaderVersion == reader.getVersion()) {
return bitSet;
BitSet bits = filter.bits(reader);
BitSetCache bitSetCache = new BitSetCache();
bitSetCache.indexReaderVersion = reader.getVersion();
bitSetCache.bitSet = new SoftReference<BitSet>(bits);
filterCache.put(key, bitSetCache);
return bits;

private class BitSetCache {
long indexReaderVersion;
SoftReference<BitSet> bitSet;

There are two additional features that this query filter doesn't implements that you may want to consider.

1st - Provide per query locking around the bitset creation code. This would allow multiple bitset creation calls to occur at once, but the same access control query would block. Therefore we would only have to build it once, even if multiple user queries with the same access control hit the query filter at once.

2nd - Persist the bitsets. In the past I have used the same directory as the index, but you may want to use a database, or something else.

From near @ infinity blog

Published at DZone with permission of its author, Aaron McCurry.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Bruce Ritchie replied on Tue, 2008/10/07 - 4:30pm

Extremely simplistic. In most systems attempting to persist acl is completely infeasible if only because updates to an acl might touch millions of pieces of content. I believe the Lucene in Action book covers better ways to accomplish this.

Aaron McCurry replied on Tue, 2008/10/07 - 6:49pm in response to: Bruce Ritchie

On our project, we index enough information to be able to search and find everything that a user has access to read.  The record may be called out by an id, or a label, or possibility (like my example) a field that used only for access control.

Also in our system, we do not make access control decisions.  They are handled by another application, we only enforce the rules.

So if you have access control needs that label each row with one or more user id's and you have millions of documents like this to update when you need to update user access.  Then yes you are correct, it will take a long time (a few hours) to update all those documents with new access controls.

However I would recommend trying to figure out a way to make groups of users.  This will help performance no matter what kind system or technology you are using.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.