• Home
• Piwik
• DataTable

PHP Class Piwik\DataTable

### The Basics DataTables consist of rows and each row consists of columns. A column value can be a numeric, a string or an array. Every row has an ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}. DataTables are hierarchical data structures. Each row can also contain an additional nested sub-DataTable (commonly referred to as a 'subtable'). Both DataTables and DataTable rows can hold **metadata**. _DataTable metadata_ is information regarding all the data, such as the site or period that the data is for. _Row metadata_ is information regarding that row, such as a browser logo or website URL. Finally, all DataTables contain a special _summary_ row. This row, if it exists, is always at the end of the DataTable. ### Populating DataTables Data can be added to DataTables in three different ways. You can either: 1. create rows one by one and add them through {@link addRow()} then truncate if desired, 2. create an array of DataTable\Row instances or an array of arrays and add them using {@link addRowsFromArray()} or {@link addRowsFromSimpleArray()} then truncate if desired, 3. or set the maximum number of allowed rows (with {@link setMaximumAllowedRows()}) and add rows one by one. If you want to eventually truncate your data (standard practice for all Piwik plugins), the third method is the most memory efficient. It is, unfortunately, not always possible to use since it requires that the data be sorted before adding. ### Manipulating DataTables There are two ways to manipulate a DataTable. You can either: 1. manually iterate through each row and manipulate the data, 2. or you can use predefined filters. A filter is a class that has a 'filter' method which will manipulate a DataTable in some way. There are several predefined Filters that allow you to do common things, such as, - add a new column to each row, - add new metadata to each row, - modify an existing column value for each row, - sort an entire DataTable, - and more. Using these filters instead of writing your own code will increase code clarity and reduce code redundancy. Additionally, filters have the advantage that they can be applied to DataTable\Map instances. So you can visit every DataTable in a {@link DataTable\Map} without having to write a recursive visiting function. All predefined filters exist in the **Piwik\DataTable\BaseFilter** namespace. _Note: For convenience, anonymous functions can be used as DataTable filters._ ### Applying Filters Filters can be applied now (via {@link filter()}), or they can be applied later (via {@link queueFilter()}). Filters that sort rows or manipulate the number of rows should be applied right away. Non-essential, presentation filters should be queued. ### Learn more - See **{@link ArchiveProcessor}** to learn how DataTables are persisted. ### Examples **Populating a DataTable** adding one row at a time $dataTable = new DataTable(); $dataTable->addRow(new Row(array( Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), Row::METADATA => array('url' => 'http://thing1.com') ))); $dataTable->addRow(new Row(array( Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2), Row::METADATA => array('url' => 'http://thing2.com') ))); using an array of rows $dataTable = new DataTable(); $dataTable->addRowsFromArray(array( array( Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), Row::METADATA => array('url' => 'http://thing1.com') ), array( Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2), Row::METADATA => array('url' => 'http://thing2.com') ) )); using a "simple" array $dataTable->addRowsFromSimpleArray(array( array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2) )); **Getting & setting metadata** $dataTable = \Piwik\Plugins\Referrers\API::getInstance()->getSearchEngines($idSite = 1, $period = 'day', $date = '2007-07-24'); $oldPeriod = $dataTable->metadata['period']; $dataTable->metadata['period'] = Period\Factory::build('week', Date::factory('2013-10-18')); **Serializing & unserializing** $maxRowsInTable = Config::getInstance()->General['datatable_archiving_maximum_rows_standard'];j $dataTable = // ... build by aggregating visits ... $serializedData = $dataTable->getSerialized($maxRowsInTable, $maxRowsInSubtable = $maxRowsInTable, $columnToSortBy = Metrics::INDEX_NB_VISITS); $serializedDataTable = $serializedData[0]; $serailizedSubTable = $serializedData[$idSubtable]; **Filtering for an API method** public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false) { $dataTable = Archive::getDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded); $dataTable->filter('Sort', array(Metrics::INDEX_NB_VISITS, 'desc', $naturalSort = false, $expanded)); $dataTable->queueFilter('ReplaceColumnNames'); $dataTable->queueFilter('ColumnCallbackAddMetadata', array('label', 'url', __NAMESPACE__ . '\getUrlFromLabelForMyReport')); return $dataTable; } Show file Open project: piwik/piwik Class Usage Examples

Protected Properties

Property	Type	Description
$currentId	integer	Id assigned to the DataTable, used to lookup the table using the DataTable_Manager
$depthLevel	integer	Current depth level of this data table 0 is the parent data table
$disabledFilters	array	List of disabled filter names eg 'Limit' or 'Sort'
$enableRecursiveFilters	boolean	When the table and all subtables are loaded, this flag will be set to true to ensure filters are applied to all subtables
$enableRecursiveSort	boolean	Defaults to false for performance reasons (most of the time we don't need recursive sorting so we save a looping over the dataTable)
$indexNotUpToDate	boolean	This flag is set to false once we modify the table in a way that outdates the index
$maximumAllowedRows	integer	If adding more rows is attempted, the extra rows get summed to the summary row.
$queuedFilters	array	List of BaseFilter queued to this table
$rebuildIndexContinuously	boolean	This is to optimize and not rebuild the full Index in the case where we add row, getRowFromLabel, addRow, getRowFromLabel thousands of times.
$rows	Piwik\DataTable\Row[]	Array of Row
$rowsCountBeforeLimitFilter	integer	We keep track of the number of rows before applying the LIMIT filter that deletes some rows
$rowsIndexByLabel	array
$summaryRow	Piwik\DataTable\Row
$tableSortedBy	string	Column name of last time the table was sorted

Public Methods

Method	Description
__clone ( )	Clone. Called when cloning the datatable. We need to make sure to create a new datatableId.
__construct ( )	Constructor. Creates an empty DataTable.
__destruct ( )	Destructor. Makes sure DataTable memory will be cleaned up.
__sleep ( )
__toString ( ) : string	Returns a string representation of this DataTable for convenient viewing.
addDataTable ( DataTable $tableToSum )	Sums a DataTable to this one.
addRow ( Row $row ) : Row	Adds a row to this table.
addRowFromArray ( array $row )	Adds a new row from an array.
addRowFromSimpleArray ( array $row )	Adds a new row a from an array of column values.
addRowsFromArray ( array $array )	Adds multiple rows from an array.
addRowsFromSerializedArray ( string $serialized )	Adds a set of rows from a serialized DataTable string.
addRowsFromSimpleArray ( array $array )	Adds multiple rows from an array containing arrays of column values.
addSummaryRow ( Row $row ) : Row	Sets the summary row.
applyQueuedFilters ( )	Applies all filters that were previously queued to the table. See {@link queueFilter()} for more information.
clearQueuedFilters ( )	Unsets all queued filters.
deleteColumn ( string $name )	Delete a column by name in every row. This change is NOT applied recursively to all subtables.
deleteColumns ( array $names, boolean $deleteRecursiveInSubtables = false )	Deletes several columns by name in every row.
deleteRow ( integer $id )	Deletes a row by ID.
deleteRows ( array $rowIds )	Deletes a set of rows by ID.
deleteRowsOffset ( integer $offset, integer | null $limit = null ) : integer	Deletes rows from $offset to $offset + $limit.
disableFilter ( string $className )	Disable a specific filter to run on this DataTable in case you have already applied this filter or if you will handle this filter manually by using a custom filter. Be aware if you disable a given filter, that filter won't be ever executed. Even if another filter calls this filter on the DataTable.
disableRecursiveFilters ( )
enableRecursiveFilters ( )	Enables recursive filtering. If this method is called then the {@link filter()} method will apply filters to every subtable in addition to this instance.
enableRecursiveSort ( )	Enables recursive sorting. If this method is called {@link sort()} will also sort all subtables.
filter ( string | Closur\Closure $className, array $parameters = [] )	Applies a filter to this datatable.
filterSubtables ( string | Closur\Closure $className, array $parameters = [] )	Applies a filter to all subtables but not to this datatable.
fromSerializedArray ( string $data ) : DataTable	Creates a new DataTable instance from a serialized DataTable string.
getAllTableMetadata ( ) : array	Returns all table metadata.
getColumn ( string $name ) : array	Returns an array containing all column values for the requested column.
getColumns ( ) : array	Returns the names of every column this DataTable contains. This method will return the columns of the first row with data and will assume they occur in every other row as well.
getColumnsStartingWith ( string $namePrefix ) : array	Returns an array containing all column values of columns whose name starts with $name.
getEmptyClone ( boolean $keepFilters = true ) : DataTable	Returns an empty DataTable with the same metadata and queued filters as $this one.
getFirstRow ( ) : Row | false	Returns the first row of the DataTable.
getId ( ) : integer	Returns the DataTable ID.
getIterator ( ) : ArrayIterator | Row[]
getLastRow ( ) : Row | false	Returns the last row of the DataTable. If there is a summary row, it will always be considered the last row.
getMetadata ( string $name ) : mixed | false	Returns metadata by name.
getRowFromId ( integer $id ) : Row | false	Returns a row by ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}.
getRowFromIdSubDataTable ( integer $idSubTable ) : Row | false	Returns the row that has a subtable with ID matching $idSubtable.
getRowFromLabel ( string $label ) : Row | false	Returns the Row whose 'label' column is equal to $label.
getRowIdFromLabel ( string $label ) : integer	Returns the row id for the row whose 'label' column is equal to $label.
getRows ( ) : Row[]	Returns the array of Rows.
getRowsCount ( ) : integer	Returns the number of rows in the table including the summary row.
getRowsCountRecursive ( ) : integer	Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable summed with the row count of each descendant subtable.
getRowsCountWithoutSummaryRow ( )
getRowsMetadata ( string $name ) : array	Returns an array containing the requested metadata value of each row.
getRowsWithoutSummaryRow ( )
getSerialized ( integer $maximumRowsInDataTable = null, integer $maximumRowsInSubDataTable = null, string $columnToSortByBeforeTruncation = null ) : array	Serializes an entire DataTable hierarchy and returns the array of serialized DataTables.
getSortedByColumnName ( ) : false | string	Returns the name of the column this table was sorted by (if any).
isEqual ( DataTable $table1, DataTable $table2 ) : boolean	Returns true if both DataTable instances are exactly the same.
isSortRecursiveEnabled ( )
makeFromIndexedArray ( array $array, array | null $subtablePerLabel = null ) : DataTable	Rewrites the input $array
makeFromSimpleArray ( array $array ) : DataTable	Returns a new DataTable created with data from a 'simple' array.
mergeSubtables ( string | boolean $labelColumn = false, boolean $useMetadataColumn = false ) : DataTable	Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables.
offsetExists ( $offset )
offsetGet ( $offset )
offsetSet ( $offset, $value )
offsetUnset ( $offset )
queueFilter ( string | Closur\Closure $className, array $parameters = [] )	Adds a filter and a list of parameters to the list of queued filters. These filters will be executed when {@link applyQueuedFilters()} is called.
queueFilterSubtables ( string | Closur\Closure $className, array $parameters = [] )	Adds a filter and a list of parameters to the list of queued filters of all subtables. These filters will be executed when {@link applyQueuedFilters()} is called.
rebuildIndex ( )	Rebuilds the index used to lookup a row by label
renameColumn ( string $oldName, string $newName )	Rename a column in every row. This change is applied recursively to all subtables.
setAllTableMetadata ( $metadata )	Sets metadata, erasing existing values.
setLabelsHaveChanged ( )
setMaximumAllowedRows ( integer $maximumAllowedRows )	Sets the maximum number of rows allowed in this datatable (including the summary row). If adding more then the allowed number of rows is attempted, the extra rows are summed to the summary row.
setMaximumDepthLevelAllowedAtLeast ( integer $atLeastLevel )	Sets the maximum depth level to at least a certain value. If the current value is greater than $atLeastLevel, the maximum nesting level is not changed.
setMetadata ( string $name, mixed $value )	Sets a metadata value by name.
setMetadataValues ( array $values )	Sets several metadata values by name.
setRows ( $rows )
setTableSortedBy ( $column )
sort ( string $functionCallback, string $columnSortedBy )	Sorts the DataTable rows using the supplied callback function.
walkPath ( array $path, array | boolean $missingRowColumns = false, integer $maxSubtableRows ) : array	Traverses a DataTable tree using an array of labels and returns the row it finds or false if it cannot find one. The number of path segments that were successfully walked is also returned.

Protected Methods

Method	Description
aggregateRowFromSimpleTable ( $row )
aggregateRowWithLabel ( Row $row, $columnAggregationOps )	Aggregates the $row columns to this table.

Private Methods

Method	Description
unserializeRows ( string $serialized ) : array	It is faster to unserialize existing serialized Row instances to "Piwik_DataTable_SerializedRow" and access the $row->c property than implementing a "__wakeup" method in the Row instance to map the "$row->c" to $row->columns etc. We're talking here about 15% faster reports aggregation in some cases. To be concrete: We have a test where Archiving a year takes 1700 seconds with "__wakeup" and 1400 seconds with this method. Yes, it takes 300 seconds to wake up millions of rows. We should be able to remove this code here end 2015 and use the "__wakeup" way by then.

Method Details

Property Details