Indexing inlinks and outlinks with Nutch 1.x

Nutch its an amazing piece of software, its one of the most versatile Web crawlers out there. I’ve been playing with Nutch for quite some time now, since version 1.3 (If my memory doesn’t play tricks with me). The truth be told Nutch do all the hard lifting of running a crawl over the Internet, Intranet or just on those sites you want to crawl. Also, Nutch gives the user the ability of changing it’s own behavior using configurations.

During the crawl life cycle Nutch needs to pay attention to the outlinks of any given page, this is how Nutch knows where to go next. Of course this outlinks could be affected by a set of configuration options in your nutch-site.xml file, but this configurations are out of the reach of this blog post.

So now we know that Nutch has the capabilities of handling outlinks and inlinks, but how can we index this inlinks and outlinks into Solr? Being able of indexing the inlinks and outlinks could be what you want, depending of your use case. Sadly Nutch doesn’t do this by default, but it’s no problem to add this custom logic trough a plugin.

Nutch provides several extension points which basically corresponds to the kind of plugins you can develop to extend Nutch beyond your wildest dreams. Generalizing our requirement we could say that what we need to do is to index (send to our persistence layer) some data that Nutch already has. So what we need is to implement and IndexingFilter plugin to carry on our task.

Important Note: If you just want to “grab and use” here is the link to the Github repo where I’ve uploaded the full code (with tests included) so you could just build and add the jar into your nutch installation.

If you’re still reading down here then, let’s start with the “technical stuff”. What we need to do is grab the outlinks and inlinks of a Webpage before its send into Solr (or some other backend), as I previously say what we need is an IndexingFilter plugin, basically an IndexingFilter plugin is just a custom class that implements the IndexingFilter interface. This interface has it’s own magic sauce inside it, but it’s way beyond our blog post, so to keep it simple let’s say that this interface force us to implement three methods:

  • filter
  • setConf
  • getConf

Both setConf and getConf are pretty straight forward if you don’t want to provide any kind of configuration options to your plugin; We won’t cover how to handle configuration options for your custom plugins, but it’s enough to say that the Configuration object provided by Hadoop requires a no brainer to use.

So let’s focus on the filter() method which is the one with the greater amount of “condiment”. Basically this method take a few arguments:

public NutchDocument filter(NutchDocument doc, Parse parse, Text url, CrawlDatum datum, Inlinks inlinks) { … }

An instance of a NutchDocument, which is the object that eventually will be passed into an indexer (Solr by default) which will persist the documents. The instance of the Parse class holds all the data that Tika and all the parser plugins has extracted from the web page’s raw content. Of course the url of the webpage being indexed; an instance of the CrawlDatum class, this holds all the crawl related information: status, fetch time, fetch interval, modified time and a lot of other information. And finally but not least an instance of the Inlinks class. Let’s take a moment so we we could realize that we just found the inlinks of any webpage, which solves like the 50% of our problem.

The outlinks could not be so far away, but let’s hold that thought for a moment and see how the filter method suppose to work:

The filter method accepts a NutchDocument as a parameter and returns a NutchDocument, so it basically takes a document add or removes data from this documents (the data of a NutchDocument it’s called a Field, which is an instance of NutchField class.

So, basically the NutchDocument provides a way to store important data, basically information that we would like to persist into our backend, totally agnostic about the persistance layer we want to use: all what an Indexer plugin needs it’s a nutch document that will holds all the data, later on an actual Indexer of your choosing will translate what is stored in a NutchDocument into your persistance layer, which could be: Solr or Elasticseach (both bundled with the default installation of Nutch 1.8 at the time of writing this blog post) or even anything you could think of, even a queue like Kafka or RabbitMQ. The next figure illustrates this process that we just described, summarizing and IndexingFilter plugin it’s only responsible of adding or removing fields from a NutchDocument.

 Nutch Indexing filters life cycle

As we see saw previously the filter method of the IndexingFilter interface receives all the inlinks of the webpage (or URL) being processed at the moment. So what we need to do in our custom plugin is just add a new inlink field into the NutchDocument, so basically something like this:

Iterator<Inlink> iterator = inlinks.iterator();
while (iterator.hasNext()) {
String linkUrl =;
doc.add("inlinks", linkUrl);
view raw hosted with ❤ by GitHub

In this case the add method of the NutchDocument field, handles the case for multivalued fields, so in case of need it “converts” a common field into a multivalued one. Meaning that multivalued fields can save as many values as we want within the same key, in this case a webpage could have several inlinks and several outlinks. Note: You’ll need to add to your Solr configuration the fields required to store the inlinks and outlinks, the main requirement in this case is that the field needs to be multivalued to hold all the inlinks of one document, of course the type of analyzers, tokenizers, etc. that you configure for this field depends on your specific use case. So now we just solved the 50% of our problem, but how to deal with the outlinks? Well as we just say in the beginning of this post, Nutch use outlinks to continue surfing throw the Web, so in some place the outlinks must be stored, this place is in the Parse information, which has a lot of sense if you ask me, basically the outlinks are extracted from the raw content of the Web page, if is an HTML document, you’ll need to search in it’s content and find all those tags that contains an outlink. So to index the outlinks we’ll need to add this snippet of code:

Outlink[] outlinks = parse.getData().getOutlinks();
if (outlinks != null) {
for (Outlink outlink : outlinks) {
doc.add("outlinks", outlink.getToUrl());
view raw hosted with ❤ by GitHub

A working plugin, if you just want to grab an use a custom indexing plugin to index your inlinks and outlinks your could clone this GitHub repo. This plugin relies on a few options to let you configure how you want to store your inlinks and outlinks, for instance it allows you to filter over your inlinks and outlinks to store only those links from a different host that the webpage being processed, so you could just keep those “external” links, and forget about all the inlinks of the same host.

If you want to know more about the plugin you should read the README and see how you could configure this plugin. I also encourage you to look into the code, the same technique explained here is used.

So, this all folks, I hope you’ve enjoyed the journey through this very large post. If you have any question, put it in a comment or contact me on Twitter.

2 thoughts on “Indexing inlinks and outlinks with Nutch 1.x

  1. A big thank you for this really valuable post. Nutch needs some more documentation and examples like this. I remembered how I struggle at the beginning to code a generic xsl parser to process all tika outputs.
    I think I’ll create a wiki to give my experience too.

    What I really like is the figure. It is so much more efficient than explaining it by endless sentences.

    1. Thanks a lot for your comment, I really appreciate it, sorry for the delayed response do. And I agree with you, Nutch needs a little more documentation on how to customize it. The default plugins are awesome, but in general you’ll need to work you way around it, to extract the content you want.

      I think that the figure is an easier way to understand how the plugins works, I might create another post to explain a few more extension points, the idea it’s basically the same.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s