TSMeta

java.lang.Object
- net.opentsdb.meta.TSMeta

```
public final class TSMeta
extends Object
```
Timeseries Metadata is associated with a particular series of data points and includes user configurable values and some stats calculated by OpenTSDB. Whenever a new timeseries is recorded, an associated TSMeta object will be stored with only the tsuid field configured. These meta objects may then be used to determine what combinations of metrics and tags exist in the system.
When you call syncToStorage(net.opentsdb.core.TSDB, boolean) on this object, it will verify that the associated UID objects this meta data is linked with still exist. Then it will fetch the existing data and copy changes, overwriting the user fields if specific (e.g. via a PUT command). If overwriting is not called for (e.g. a POST was issued), then only the fields provided by the user will be saved, preserving all of the other fields in storage. Hence the need for the changed hash map and the syncMeta(net.opentsdb.meta.TSMeta, boolean) method.
The metric and tag UIDMeta objects may be loaded from their respective locations in the data storage system if requested. Note that this will cause at least 3 extra storage calls when loading.

Since:

2.0

Constructor Summary

Constructors
Constructor and Description
`TSMeta()` Default constructor necessary for POJO de/serialization
`TSMeta(byte[] tsuid, long created)` Constructor for new timeseries that initializes the created and last_received times to the current system time
`TSMeta(String tsuid)` Constructor for RPC timeseries parsing that will not set the timestamps

Method Summary

Methods
Modifier and Type	Method and Description
`static byte[]`	`COUNTER_QUALIFIER()`
`static com.stumbleupon.async.Deferred<Boolean>`	`counterExistsInStorage(TSDB tsdb, byte[] tsuid)` Determines if the counter column exists for the TSUID.
`com.stumbleupon.async.Deferred<Object>`	`delete(TSDB tsdb)` Attempts to delete the meta object from storage
`static byte[]`	`FAMILY()`
`long`	`getCreated()`
`Map<String,String>`	`getCustom()`
`String`	`getDataType()`
`String`	`getDescription()`
`String`	`getDisplayName()`
`long`	`getLastReceived()`
`double`	`getMax()`
`UIDMeta`	`getMetric()`
`double`	`getMin()`
`String`	`getNotes()`
`int`	`getRetention()`
`List<UIDMeta>`	`getTags()`
`long`	`getTotalDatapoints()`
`static com.stumbleupon.async.Deferred<TSMeta>`	`getTSMeta(TSDB tsdb, String tsuid)` Attempts to fetch the timeseries meta data and associated UIDMeta objects from storage.
`String`	`getTSUID()`
`String`	`getUnits()`
`static com.stumbleupon.async.Deferred<Long>`	`incrementAndGetCounter(TSDB tsdb, byte[] tsuid)` Increments the tsuid datapoint counter or creates a new counter.
`static byte[]`	`META_QUALIFIER()`
`static com.stumbleupon.async.Deferred<Boolean>`	`metaExistsInStorage(TSDB tsdb, String tsuid)` Determines if an entry exists in storage or not.
`static com.stumbleupon.async.Deferred<TSMeta>`	`parseFromColumn(TSDB tsdb, org.hbase.async.KeyValue column, boolean load_uidmetas)` Parses a TSMeta object from the given column, optionally loading the UIDMeta objects
`void`	`setCreated(long created)`
`void`	`setCustom(Map<String,String> custom)`
`void`	`setDataType(String data_type)`
`void`	`setDescription(String description)`
`void`	`setDisplayName(String display_name)`
`void`	`setMax(double max)`
`void`	`setMin(double min)`
`void`	`setNotes(String notes)`
`void`	`setRetention(int retention)`
`void`	`setUnits(String units)`
`com.stumbleupon.async.Deferred<Boolean>`	`storeNew(TSDB tsdb)` Attempts to store a new, blank timeseries meta object via a CompareAndSet Note: This should not be called by user accessible methods as it will overwrite any data already in the column.
`com.stumbleupon.async.Deferred<Boolean>`	`syncToStorage(TSDB tsdb, boolean overwrite)` Attempts a CompareAndSet storage call, loading the object from storage, synchronizing changes, and attempting a put.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - TSMeta
```
public TSMeta()
```
    Default constructor necessary for POJO de/serialization
  - TSMeta
```
public TSMeta(String tsuid)
```
    Constructor for RPC timeseries parsing that will not set the timestamps
    
    Parameters:
    tsuid - The UID of the timeseries
  - TSMeta
```
public TSMeta(byte[] tsuid,
      long created)
```
    Constructor for new timeseries that initializes the created and last_received times to the current system time
    
    Parameters:
    tsuid - The UID of the timeseries
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Returns:
    a string with details about this object
  - delete
```
public com.stumbleupon.async.Deferred<Object> delete(TSDB tsdb)
```
    Attempts to delete the meta object from storage
    
    Parameters:
    tsdb - The TSDB to use for access to storage
    
    Returns:
    A deferred without meaning. The response may be null and should only be used to track completion.
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue
    
    IllegalArgumentException - if data was missing (uid and type)
  - syncToStorage
```
public com.stumbleupon.async.Deferred<Boolean> syncToStorage(TSDB tsdb,
                                                    boolean overwrite)
```
    Attempts a CompareAndSet storage call, loading the object from storage, synchronizing changes, and attempting a put. Also verifies that associated UID name mappings exist before merging. Note: If the local object didn't have any fields set by the caller or there weren't any changes, then the data will not be written and an exception will be thrown. Note: We do not store the UIDMeta information with TSMeta's since users may change a single UIDMeta object and we don't want to update every TSUID that includes that object with the new data. Instead, UIDMetas are merged into the TSMeta on retrieval so we always have canonical data. This also saves space in storage.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    overwrite - When the RPC method is PUT, will overwrite all user accessible fields
    
    Returns:
    True if the storage call was successful, false if the object was modified in storage during the CAS call. If false, retry the call. Other failures will result in an exception being thrown.
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue
    
    IllegalArgumentException - if parsing failed
    
    NoSuchUniqueId - If any of the UID name mappings do not exist
    
    IllegalStateException - if the data hasn't changed. This is OK!
    
    JSONException - if the object could not be serialized
  - storeNew
```
public com.stumbleupon.async.Deferred<Boolean> storeNew(TSDB tsdb)
```
    Attempts to store a new, blank timeseries meta object via a CompareAndSet Note: This should not be called by user accessible methods as it will overwrite any data already in the column. Note: This call does not guarantee that the UIDs exist before storing as it should only be called *after* a data point has been recorded or during a meta sync.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    
    Returns:
    True if the CAS completed successfully (and no TSMeta existed previously), false if something was already stored in the TSMeta column.
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue fetching
    
    IllegalArgumentException - if parsing failed
    
    JSONException - if the object could not be serialized
  - getTSMeta
```
public static com.stumbleupon.async.Deferred<TSMeta> getTSMeta(TSDB tsdb,
                                               String tsuid)
```
    Attempts to fetch the timeseries meta data and associated UIDMeta objects from storage. Note: Until we have a caching layer implemented, this will make at least 4 reads to the storage system, 1 for the TSUID meta, 1 for the metric UIDMeta and 1 each for every tagk/tagv UIDMeta object.
    See getFromStorage(TSDB, byte[]) for details.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The UID of the meta to fetch
    
    Returns:
    A TSMeta object if found, null if not
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue fetching
    
    IllegalArgumentException - if parsing failed
    
    JSONException - if the data was corrupted
    
    NoSuchUniqueName - if one of the UIDMeta objects does not exist
  - parseFromColumn
```
public static com.stumbleupon.async.Deferred<TSMeta> parseFromColumn(TSDB tsdb,
                                                     org.hbase.async.KeyValue column,
                                                     boolean load_uidmetas)
```
    Parses a TSMeta object from the given column, optionally loading the UIDMeta objects
    
    Parameters:
    tsdb - The TSDB to use for storage access
    column - The KeyValue column to parse
    load_uidmetas - Whether or not UIDmeta objects should be loaded
    
    Returns:
    A TSMeta if parsed successfully
    
    Throws:
    
    NoSuchUniqueName - if one of the UIDMeta objects does not exist
    
    JSONException - if the data was corrupted
  - metaExistsInStorage
```
public static com.stumbleupon.async.Deferred<Boolean> metaExistsInStorage(TSDB tsdb,
                                                          String tsuid)
```
    Determines if an entry exists in storage or not. This is used by the UID Manager tool to determine if we need to write a new TSUID entry or not. It will not attempt to verify if the stored data is valid, just checks to see if something is stored in the proper column.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The UID of the meta to verify
    
    Returns:
    True if data was found, false if not
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue fetching
  - counterExistsInStorage
```
public static com.stumbleupon.async.Deferred<Boolean> counterExistsInStorage(TSDB tsdb,
                                                             byte[] tsuid)
```
    Determines if the counter column exists for the TSUID. This is used by the UID Manager tool to determine if we need to write a new TSUID entry or not. It will not attempt to verify if the stored data is valid, just checks to see if something is stored in the proper column.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The UID of the meta to verify
    
    Returns:
    True if data was found, false if not
    
    Throws:
    
    org.hbase.async.HBaseException - if there was an issue fetching
  - incrementAndGetCounter
```
public static com.stumbleupon.async.Deferred<Long> incrementAndGetCounter(TSDB tsdb,
                                                          byte[] tsuid)
```
    Increments the tsuid datapoint counter or creates a new counter. Also creates a new meta data entry if the counter did not exist. Note: This method also:
    - Passes the new TSMeta object to the Search plugin after loading UIDMeta objects
    - Passes the new TSMeta through all configured trees if enabled
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The TSUID to increment or create
    
    Returns:
    0 if the put failed, a positive LONG if the put was successful
    
    Throws:
    
    org.hbase.async.HBaseException - if there was a storage issue
    
    JSONException - if the data was corrupted
    
    NoSuchUniqueName - if one of the UIDMeta objects does not exist
  - META_QUALIFIER
```
public static byte[] META_QUALIFIER()
```
    Returns:
    The configured meta data column qualifier byte array
  - COUNTER_QUALIFIER
```
public static byte[] COUNTER_QUALIFIER()
```
    Returns:
    The configured counter column qualifier byte array
  - FAMILY
```
public static byte[] FAMILY()
```
    Returns:
    The configured meta data family byte array
  - getTSUID
```
public final String getTSUID()
```
    Returns:
    the TSUID as a hex encoded string
  - getMetric
```
public final UIDMeta getMetric()
```
    Returns:
    the metric UID meta object
  - getTags
```
public final List<UIDMeta> getTags()
```
    Returns:
    the tag UID meta objects in an array, tagk first, then tagv, etc
  - getDisplayName
```
public final String getDisplayName()
```
    Returns:
    optional display name
  - getDescription
```
public final String getDescription()
```
    Returns:
    optional description
  - getNotes
```
public final String getNotes()
```
    Returns:
    optional notes
  - getCreated
```
public final long getCreated()
```
    Returns:
    when the TSUID was first recorded, Unix epoch
  - getCustom
```
public final Map<String,String> getCustom()
```
    Returns:
    optional custom key/value map, may be null
  - getUnits
```
public final String getUnits()
```
    Returns:
    optional units
  - getDataType
```
public final String getDataType()
```
    Returns:
    optional data type
  - getRetention
```
public final int getRetention()
```
    Returns:
    optional retention, default of 0 means retain indefinitely
  - getMax
```
public final double getMax()
```
    Returns:
    optional max value, set by the user
  - getMin
```
public final double getMin()
```
    Returns:
    optional min value, set by the user
  - getLastReceived
```
public final long getLastReceived()
```
    Returns:
    the last received timestamp, Unix epoch
  - getTotalDatapoints
```
public final long getTotalDatapoints()
```
    Returns:
    the total number of data points as tracked by the meta data
  - setDisplayName
```
public final void setDisplayName(String display_name)
```
    Parameters:
    display_name - an optional name for the timeseries
  - setDescription
```
public final void setDescription(String description)
```
    Parameters:
    description - an optional description
  - setNotes
```
public final void setNotes(String notes)
```
    Parameters:
    notes - optional notes
  - setCreated
```
public final void setCreated(long created)
```
    Parameters:
    created - the created timestamp Unix epoch in seconds
  - setCustom
```
public final void setCustom(Map<String,String> custom)
```
    Parameters:
    custom - optional key/value map
  - setUnits
```
public final void setUnits(String units)
```
    Parameters:
    units - optional units designation
  - setDataType
```
public final void setDataType(String data_type)
```
    Parameters:
    data_type - optional type of data, e.g. "counter", "gauge"
  - setRetention
```
public final void setRetention(int retention)
```
    Parameters:
    retention - optional rentention in days, 0 = indefinite
  - setMax
```
public final void setMax(double max)
```
    Parameters:
    max - optional max value for the timeseries, NaN is the default
  - setMin
```
public final void setMin(double min)
```
    Parameters:
    min - optional min value for the timeseries, NaN is the default

Class TSMeta

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TSMeta

TSMeta

TSMeta

Method Detail

toString

delete

syncToStorage

storeNew

getTSMeta

parseFromColumn

metaExistsInStorage

counterExistsInStorage

incrementAndGetCounter

META_QUALIFIER

COUNTER_QUALIFIER

FAMILY

getTSUID

getMetric

getTags

getDisplayName

getDescription

getNotes

getCreated

getCustom

getUnits

getDataType

getRetention

getMax

getMin

getLastReceived

getTotalDatapoints

setDisplayName

setDescription

setNotes

setCreated

setCustom

setUnits

setDataType

setRetention

setMax

setMin