Search

Search is a key part of DataTables and its goal of making data accessible. As such it has a number of search capabilities built in as well as presenting options to customise the search and APIs to allow advanced and case specific search operations. This document will discuss in detail how search is performed in DataTables.

Global search

The first search control you'll encounter when using DataTables is the default global search at the top right of the table. This uses the search feature and its position can be controlled with the layout option. We term this a "global" search as it will search for data across all columns. The built in search input of DataTables has the following features enabled by default:

• Search for words in any order (e.g. Today Friday will result in the same data set as Friday Today).
• Case insensitive search (e.g. Banana will give the same results as BaNaNa).
• Use double quotes to search for an exact phrase (e.g. "Export Data").
• Negative search matching using an exclamation mark before a word (e.g. !Click will find all data that does not contain the word "click").

We term the above "smart" searching and it is what the end user will typically interact with. It is designed to be similar to search engines such as Google and Kagi so the end user is immediately familiar with the interface presented in your UI.

API

The search API is where things start to get really interesting as you can customise the search option and provide your own custom search functions.

The global search API is search() and it provides the same functionality as the global search input if simply given a string:

table
    .search('"New York" -Chief')
    .draw();

You can also provide a DataTables.SearchOptions object to customise the search options above and additional options:

table.search('Chief', {
    caseInsensitive: false
});

Furthermore you can provide a search function or regular expression - this is what really opens DataTables' search abilities up to more or less anything you can imagine:

table
    .search(d => d.includes('My search term'))
    .draw();

Column search

Thus far we've discussed search across the whole table, however, there will be times when you wish to apply a search term to a specific column only. This can be done with the column().search() method. DataTables does not present column search input elements by default, however, they can readily be added, as shown in this example.

column().search() has all of the same options as the global search discussed above. One additional option that might be of specific interest for column searching is the exact option of DataTables.SearchOptions which can be useful if you give the end user a select of options, as shown in this example.

Fixed search

The search() and column().search() methods will immediately apply the given search term, overwriting any search term that was previously applied. However, sometimes you might wish to apply more that one search term at a time, stacking search terms to present complex search controls to the end user. This can be done with a "fixed" search, whereby you can give a search term a unique name (or id) and it will be applied until replaced. We term this "fixed searching".

The API methods are search.fixed() and column().search.fixed(). They both work in exactly the same way as the methods discussed above, but allow multiple search terms to be used at the same time.

For example, the following will create a fixed search called "citySearch" which will remain unless it is replaced. The end user may then use the input from search to provide their own search terms in addition to this one:

table.search.fixed('citySearch', 'Paris');

Fixed search is particularly useful if you are developing a plug-in for DataTables which you wish to be reusable, since it reduces the chance of search terms conflicting.

Extensions

The search feature is the only search input control that DataTables has built in by default. However, we also produce a number of extensions for DataTables that provide more advantaged search inputs:

• SearchBuilder to let the end user build up complex search expressions
• SearchPanes to display lists of data that can be used to search the main table.

Other plug-ins can readily be created, such as this alphabet search control. If you create a search plug-in for DataTables, let us know!

Legacy search

Prior to DataTables 2 search functions had to be added to DataTables using the DataTable.ext.search array, which contained a list of functions. This method had a number of disadvantages including the fact that the search was applied to all tables on a page and extra logic was required to limit it to a specific table.

Support for DataTable.ext.search has been retained in DataTables 2 for backwards compatibility, but new projects should not use this API, and old projects should be ported to the new APIs.

The following information is retained for anyone using DataTables 1.x. Do not create new projects which use this API.

Legacy plug-in search functions for DataTables should be attached to the DataTable.ext.search array.

Inputs

The function takes five input parameters:

1. object - DataTables settings object (see settings()).
2. array - Array of the search data for the row. The array has one element for each column in the table.
3. integer - The index for the row in question (see row().index()).
4. object or array - The original data source for the row. This will be the array or object that was given to DataTables as the data source for the row.
5. integer - Search counter.

It is important to note the difference between parameters 2 and 4 as they are potentially similar and can carry the same data. The array given as the second parameter is the search data for the row, while the fourth parameter is the original data object for the row.

Return

The plug-in search function should return a boolean value:

• true - The row should be included in the search results
• false - The row should be removed from the search results

Example

The following example shows a range search taking data from two input elements (#min and #max) into which an end user would enter numeric data to search the table. Some logic operation is performed (in this case a numeric range check) and the boolean value is returned.

DataTable.ext.search.push(
    function( settings, searchData, index, rowData, counter ) {
        var min = parseInt( $('#min').val(), 10 );
        var max = parseInt( $('#max').val(), 10 );
        var age = parseFloat( searchData[3] ) || 0; // using the data from the 4th column
 
        if ( ( isNaN( min ) && isNaN( max ) ) ||
             ( isNaN( min ) && age <= max ) ||
             ( min <= age   && isNaN( max ) ) ||
             ( min <= age   && age <= max ) )
        {
            return true;
        }
        return false;
    }
);

If you are interested, this example demonstrates how the above code might be migrated to DataTables 2.