Back to Top

ValueTable

In this topic

  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample

Summary

A value table is a flexible table-like object, made up of rows and columns containing various values.

Discussion

Native Python objects such as long, str, bool, double, datetime.datetime() are supported by the ValueTable object. These are often easier to work with and make the code more reliable on different computers, especially for types such as GPDate, which requires system-specific parsing when converted to and from a string. To retrieve Python objects from the ValueTable object, use the getTrueValue and getTrueRow functions. To add or write Python objects to the ValueTable object, use the setValue and addRow functions.

For a list of supported column data types, see Data types.

Syntax

 ValueTable  ({columns})
ParameterExplanationData Type
columns

Adds columns to the ValueTable object. The value can be as follows:

  • The number of columns as an integer. Each column will be added as a GPString data type.
  • The data type of a single column as a string, for example, "GPString".
  • The data types of multiple columns as a list of strings, for example, ["GPDate", "GPLong"].

(The default value is 1)

Integer

Properties

PropertyExplanationData Type
columnCount
(Read Only)

The number of columns.

Integer
rowCount
(Read Only)

The number of rows.

Integer

Method Overview

MethodExplanation
addColumns (number_of_columns)

Adds columns to the ValueTable object. The value can be as follows:

  • The number of columns as an integer. Each column will be added as a GPString data type.
  • The data type of a single column as a string, for example, "GPString".
  • The data types of multiple columns as a list of strings, for example, ["GPDate", "GPLong"].

The addColumns method is functionally equivalent to the setColumns method.

addRow (value)

Adds a row with specified values to the value table.

exportToString ()

Exports the object to its string representation.

getRow (row)

Returns the values from the row at the specified index. The row's values are returned as a space-delimited string.

getTrueRow (row)

Returns the value from the row at the specified index. The row's values are returned as a list with appropriate Python objects.

The column data type to Python object mappings are the following:

  • Integer to int
  • Double to float
  • Boolean to bool
  • Date to datetime.datetime

getTrueValue (row, column)

Given a column and row index, returns the value as an appropriate Python object.

The column data type to Python object mappings are the following:

  • Integer to int
  • Double to float
  • Boolean to bool
  • Date to datetime.datetime

The value for all other column types are returned as strings.

getValue (row, column)

Returns the value from a given column and row as a string.

loadFromString (string)

Loads the contents of the ValueTable based on the string provided.

removeRow (row)

Deletes the row found at the specified index.

setColumns (number_of_columns)

Adds columns to the ValueTable object. The value can be as follows:

  • The number of columns as an integer. Each column will be added as a GPString data type.
  • The data type of a single column as a string, for example, "GPString".
  • The data types of multiple columns as a list of strings, for example, ["GPDate", "GPLong"].

The setColumns method is functionally equivalent to the addColumns method.

setRow (row, value)

Updates a given row within the ValueTable object.

The value argument is space-delimited. Any value that contains spaces must be enclosed in quotations. In the following example, a feature class and an index value are added to the ValueTable object with two columns.

vtab.setRow(0, "'c:/temp/land use.shp' 2")

Unlike other row operations, the setRow only supports a string value.

setValue (row, column, value)

Updates the value of a given row and column. The value can be a either a string representation or an appropriate native Python type.

For example, if the column is a date type, a datetime.datetime object or a string can be used.

# Must be system appropriate string representation of a date
vtab.setValue(0, 1, "2021-06-17") 

vtab.setValue(0, 1, datetime.datetime(2021, 6, 17)

Methods

addColumns (number_of_columns)
ParameterExplanationData Type
number_of_columns

The number of columns for the value table.

Integer
addRow (value)
ParameterExplanationData Type
value

A list of values to be added as a new row.

The value argument can be as follows:

  • A list containing appropriate native Python objects, for example, vtab.addRow(['c:/temp/land use.shp', 2]).
  • A space-delimited string representation. Values within the string that contain spaces must be enclosed in quotations, for example, vtab.addRow("'c:/temp/land use.shp' 2").

Object
exportToString ()
Return Value
Data TypeExplanation
String

The WKT string representation of the object. 

getRow (row)
ParameterExplanationData Type
row

The row index position.

Integer
Return Value
Data TypeExplanation
String

A row from the ValueTable object. 

getTrueRow (row)
ParameterExplanationData Type
row

The row index position.

Integer
Return Value
Data TypeExplanation
Object

A Python list containing the value of a given row as appropriate Python objects.

getTrueValue (row, column)
ParameterExplanationData Type
row

The row index position.

Integer
column

The column index position.

Integer
Return Value
Data TypeExplanation
String

The value of the given column and row. 

getValue (row, column)
ParameterExplanationData Type
row

The row index position.

Integer
column

The column index position.

Integer
Return Value
Data TypeExplanation
String

The value of the given column and row. 

loadFromString (string)
ParameterExplanationData Type
string

The WKT string representation of the object.

Within the string, all values are wrapped in single quotes, with each value in a row separated by a space, and each row separated by a semicolon. Each column in the ValueTable will have a data type of GPString.

String
removeRow (row)
ParameterExplanationData Type
row

The index position of the row to remove.

Integer
setColumns (number_of_columns)
ParameterExplanationData Type
number_of_columns

The number of columns for the value table.

Integer
setRow (row, value)
ParameterExplanationData Type
row

The index position of the row to update.

Integer
value

The value to update in the given row.

Object
setValue (row, column, value)
ParameterExplanationData Type
row

The row index.

Integer
column

The column index.

Integer
value

The value to update the given row and column. This can be a string representation or a native Python type (int, bool, or datetime.datetime).

Object

Code sample

ValueTable example

Use a ValueTable object to hold feature class names and ranks for the Union function.

import arcpy

# Set the workspace. List all of the feature classes in the dataset
arcpy.env.workspace = "c:/data/landbase.gdb/Wetlands"
feature_classes = arcpy.ListFeatureClasses()

# Create the value table for the Analysis toolbox Union function with 2 columns
value_table = arcpy.ValueTable(2)

# Iterate through the list of feature classes
for fc in feature_classes:
    # Update the value table with a rank of 2 for each record, except
    #   for BigBog
    if fc.lower() != "bigbog":
        value_table.addRow(fc + " 2")
    else:
        value_table.addRow(fc + " 1")

# Union the wetlands feature classes with the land use feature class to create
# a single feature class with all of the wetlands and land use data
value_table.addRow("c:/data/landbase.gdb/land_use 2")
arcpy.Union_analysis(value_table, "c:/data/landbase.gdb/wetlands_use")
ValueTable example 2

A value table can be populated with a multivalue string that has been passed to a script as an argument, making it easy to extract each record.

import os
import arcpy

# Set the output workspace
arcpy.env.workspace = arcpy.GetParameterAsText(1)

# Create a value table with 2 columns
value_table = arcpy.ValueTable(2)

# Set the values of the table with the contents of the first argument
value_table.loadFromString(arcpy.GetParameterAsText(0))

# Loop through the list of inputs
for i in range(0, value_table.rowCount):
    # Validate the output name for the new workspace
    name = value_table.getRow(i)
    out_name = arcpy.ValidateTableName(os.path.basename(name))

    # Copy the features to the new workspace
    arcpy.CopyFeatures_management(name, out_name)
ValueTable example 3

Create and add values to a ValueTable object using native Python types.

import arcpy
import datetime

# Create a value table with 2 columns
value_table = arcpy.ValueTable(["GPLong", "GPBoolean", "GPDate"])

# Set the values of the table with native Python types
value_table.addRow([1, True, datetime.datetime(2004, 12, 19)])
value_table.addRow([2, False, datetime.datetime(2008, 2, 13)])

# Retrieve true Python object from ValueTable
event_date = value_table.getTrueValue(1, 2)

Feedback on this topic?

In this topic
  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample