Datatables Server-Side Parameter Set

Server-side processing is enabled by use of the serverSideDT option, and configured usingajaxDT. See below for further information on configuration options.

Sent parameters

When making a request to the server using server-side processing, DataTables will send the following data in order to let the server know what data is required:

Parameter name	Type	Description
draw	integerJS	Draw counter. This is used by DataTables to ensure that the Ajax returns from server-side processing requests are drawn in sequence by DataTables (Ajax requests are asynchronous and thus can return out of sequence). This is used as part of the draw return parameter (see below).
start	integerJS	Paging first record indicator. This is the start point in the current data set (0 index based - i.e. 0 is the first record).
length	integerJS	Number of records that the table can display in the current draw. It is expected that the number of records returned will be equal to this number, unless the server has fewer records to return. Note that this can be -1 to indicate that all records should be returned (although that negates any benefits of server-side processing!)
search[value]	stringJS	Global search value. To be applied to all columns which have searchable as true.
search[regex]	booleanJS	true if the global filter should be treated as a regular expression for advanced searching, falseotherwise. Note that normally server-side processing scripts will not perform regular expression searching for performance reasons on large data sets, but it is technically possible and at the discretion of your script.
order[i][column]	integerJS	Column to which ordering should be applied. This is an index reference to the columns array of information that is also submitted to the server.
order[i][dir]	stringJS	Ordering direction for this column. It will be asc ordesc to indicate ascending ordering or descending ordering, respectively.
columns[i][data]	stringJS	Column's data source, as defined bycolumns.dataDT.
columns[i][name]	stringJS	Column's name, as defined by columns.nameDT.
columns[i][searchable]	booleanJS	Flag to indicate if this column is searchable (true) or not (false). This is controlled bycolumns.searchableDT.
columns[i][orderable]	booleanJS	Flag to indicate if this column is orderable (true) or not (false). This is controlled bycolumns.orderableDT.
columns[i][search][value]	stringJS	Search value to apply to this specific column.
columns[i][search][regex]	booleanJS	Flag to indicate if the search term for this column should be treated as regular expression (true) or not (false). As with global search, normally server-side processing scripts will not perform regular expression searching for performance reasons on large data sets, but it is technically possible and at the discretion of your script.

The order[i] and columns[i] parameters that are sent to the server are arrays of information:

• order[i] - is an array defining how many columns are being ordered upon - i.e. if the array length is 1, then a single column sort is being performed, otherwise a multi-column sort is being performed.
• columns[i] - an array defining all columns in the table.

In both cases, i is an integer which will change to indicate the array value. In most modern server-side scripting environments this data will automatically be available to you as an array.

Returned data

Once DataTables has made a request for data, with the above parameters sent to the server, it expects JSON data to be returned to it, with the following parameters set:

Parameter name	Type	Description
draw	integerJS	The draw counter that this object is a response to - from thedraw parameter sent as part of the data request. Note that it is strongly recommended for security reasons that youcast this parameter to an integer, rather than simply echoing back to the client what it sent in the draw parameter, in order to prevent Cross Site Scripting (XSS) attacks.
recordsTotal	integerJS	Total records, before filtering (i.e. the total number of records in the database)
recordsFiltered	integerJS	Total records, after filtering (i.e. the total number of records after filtering has been applied - not just the number of records being returned for this page of data).
data	arrayJS	The data to be displayed in the table. This is an array of data source objects, one for each row, which will be used by DataTables. Note that this parameter's name can be changed using the ajaxDT option's dataSrc property.
error	stringJS	Optional: If an error occurs during the running of the server-side processing script, you can inform the user of this error by passing back the error message to be displayed using this parameter. Do not include if there is no error.

In addition to the above parameters which control the overall table, DataTables can use the following optional parameters on each individual row's data source object to perform automatic actions for you:

Parameter name	Type	Description
DT_RowId	stringJS	Set the ID property of the tr node to this value
DT_RowClass	stringJS	Add this class to the tr node
DT_RowData	objectJS	Add the data contained in the object to the row using the jQuerydata() method to set the data, which can also then be used for later retrieval (for example on a click event).
DT_RowAttr	objectJS	Add the data contained in the object to the row tr node as attributes. The object keys are used as the attribute keys and the values as the corresponding attribute values. This is performed using using the jQuery param() method. Please note that this option requires DataTables 1.10.5 or newer.

An example of how a return looks using these options is shown below in the "Example data" section below.

Configuration

Server-side processing in DataTables is enable through use of the serverSideDT option. Simply set it to true and DataTabels will operate in server-side processing mode. You will also want to use the ajaxDT option to specify the URL where DataTables should get its Ajax data from. As such, the simplest server-side processing initialisation is:

 

  

   

    Javascript
   
   

       

        1
       
       

        2
       
       

        3
       
       

        4
       

       

        

         $(
         '#example'
         ).DataTable( {
        
        

             
         serverSide: 
         true
         ,
        
        

             
         ajax: 
         '/data-source'
        
        

         } );
        
       
  
 

Configuration of how DataTables makes the Ajax request is configured through the ajaxDT option. In the above example we used it as a string, which instructs DataTables to use its default settings for making the Ajax request. However, you can customise these settings by passing ajaxDT in as an object. As an object, ajaxDT maps directly onto the jQuery ajax configuration object, so any options you can use in a jQuery request, you can also use with DataTables! For example, to make a POST request:

 

  

   

    Javascript
   
   

       

        1
       
       

        2
       
       

        3
       
       

        4
       
       

        5
       
       

        6
       
       

        7
       

       

        

         $(
         '#example'
         ).DataTable( {
        
        

             
         serverSide: 
         true
         ,
        
        

             
         ajax: {
        
        

                 
         url: 
         '/data-source'
         ,
        
        

                 
         type: 
         'POST'
        
        

             
         }
        
        

         } );
        
       
  
 

For further information about the Ajax options available in DataTables, please refer to the ajaxDTdocumentation.

Legacy

Older versions of DataTables (1.9-) used a different set of parameters to send and receive from the server. As such scripts which are written for DataTables 1.10+ will not be able to function with DataTables 1.9-. However, DataTables 1.10 does have a compatibility mode for scripts written for 1.9-. This compatibility mode is triggered by use of the old sAjaxSource parameter (rather than the new ajaxDT parameter) or by setting $.fn.dataTable.ext.legacy.ajax = true; .

For documentation on the 1.9- method of performing server-side processing, please refer to thelegacy documentation.

Example data

Example of server-side processing return using arrays as the data source for the table (full example):

 

  

   

    Javascript
   
   

       

        1
       
       

        2
       
       

        3
       
       

        4
       
       

        5
       
       

        6
       
       

        7
       
       

        8
       
       

        9
       
       

        10
       
       

        11
       
       

        12
       
       

        13
       
       

        14
       
       

        15
       
       

        16
       
       

        17
       
       

        18
       
       

        19
       
       

        20
       
       

        21
       
       

        22
       
       

        23
       
       

        24
       

       

        

         {
        
        

             
         "draw"
         : 1,
        
        

             
         "recordsTotal"
         : 57,
        
        

             
         "recordsFiltered"
         : 57,
        
        

             
         "data"
         : [
        
        

                 
         [
        
        

                     
         "Angelica"
         ,
        
        

                     
         "Ramos"
         ,
        
        

                     
         "System Architect"
         ,
        
        

                     
         "London"
         ,
        
        

                     
         "9th Oct 09"
         ,
        
        

                     
         "$2,875"
        
        

                 
         ],
        
        

                 
         [
        
        

                     
         "Ashton"
         ,
        
        

                     
         "Cox"
         ,
        
        

                     
         "Technical Author"
         ,
        
        

                     
         "San Francisco"
         ,
        
        

                     
         "12th Jan 09"
         ,
        
        

                     
         "$4,800"
        
        

                 
         ],
        
        

                 
         ...
        
        

             
         ]
        
        

         }
        
       
  
 

Example of server-side processing return using objects, with DT_RowId and DT_RowData also included, as the data source for the table (full example):

 

  

   

    Javascript
   
   

       

        1
       
       

        2
       
       

        3
       
       

        4
       
       

        5
       
       

        6
       
       

        7
       
       

        8
       
       

        9
       
       

        10
       
       

        11
       
       

        12
       
       

        13
       
       

        14
       
       

        15
       
       

        16
       
       

        17
       
       

        18
       
       

        19
       
       

        20
       
       

        21
       
       

        22
       
       

        23
       
       

        24
       
       

        25
       
       

        26
       
       

        27
       
       

        28
       
       

        29
       
       

        30
       
       

        31
       
       

        32
       

       

        

         {
        
        

             
         "draw"
         : 1,
        
        

             
         "recordsTotal"
         : 57,
        
        

             
         "recordsFiltered"
         : 57,
        
        

             
         "data"
         : [
        
        

                 
         {
        
        

                     
         "DT_RowId"
         : 
         "row_3"
         ,
        
        

                     
         "DT_RowData"
         : {
        
        

                         
         "pkey"
         : 3
        
        

                     
         },
        
        

                     
         "first_name"
         : 
         "Angelica"
         ,
        
        

                     
         "last_name"
         : 
         "Ramos"
         ,
        
        

                     
         "position"
         : 
         "System Architect"
         ,
        
        

                     
         "office"
         : 
         "London"
         ,
        
        

                     
         "start_date"
         : 
         "9th Oct 09"
         ,
        
        

                     
         "salary"
         : 
         "$2,875"
        
        

                 
         },
        
        

                 
         {
        
        

                     
         "DT_RowId"
         : 
         "row_17"
         ,
        
        

                     
         "DT_RowData"
         : {
        
        

                         
         "pkey"
         : 17
        
        

                     
         },
        
        

                     
         "first_name"
         : 
         "Ashton"
         ,
        
        

                     
         "last_name"
         : 
         "Cox"
         ,
        
        

                     
         "position"
         : 
         "Technical Author"
         ,
        
        

                     
         "office"
         : 
         "San Francisco"
         ,
        
        

                     
         "start_date"
         : 
         "12th Jan 09"
         ,
        
        

                     
         "salary"
         : 
         "$4,800"
        
        

                 
         },
        
        

                 
         ...
        
        

             
         ]
        
        

         }
        
       
  
 

A full set of examples, exploring the options available for server-side processing is available in theexamples section of this site.