> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.
# Objects
> Every object and enum the Spreadsheets tools accept.
## Model tree
## Spreadsheet
Resource that represents a spreadsheet.
| Field | Type | Description |
| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
| `properties` | [SpreadsheetProperties](#spreadsheetproperties) | Overall properties of a spreadsheet. |
| `sheets` | [Sheet](#sheet)\[] | The sheets that are part of a spreadsheet. |
| `developerMetadata` | [DeveloperMetadata](#developermetadata)\[] | The developer metadata associated with a spreadsheet. |
| `dataSources` | [DataSource](#datasource)\[] | A list of external data sources connected with the spreadsheet. |
| `namedRanges` | [NamedRange](#namedrange)\[] | The named ranges defined in a spreadsheet. |
| `comments` | [CommentThread](#commentthread)\[] | The comment threads associated with the spreadsheet. Developer Preview. |
## SpreadsheetProperties
Properties of a spreadsheet.
| Field | Type | Description |
| ----------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `importFunctionsExternalUrlAccessAllowed` | `boolean` | Whether to allow external URL access for image and import functions. Read only when true. When false, you can set to true. This value will be bypassed and always return true if the admin has enabled the [allowlisting feature](https://support.google.com/a?p=url_allowlist). |
| `locale` | `string` | The locale of the spreadsheet in one of the following formats: \* an ISO 639-1 language code such as `en` \* an ISO 639-2 language code such as `fil`, if no 639-1 code exists \* a combination of the ISO language code and country code, such as `en_US` Note: when updating this field, not all locales/languages are supported. |
| `autoRecalc` | [RecalculationInterval](#recalculationinterval) | The amount of time to wait before volatile functions are recalculated. |
| `title` | `string` | The title of the spreadsheet. |
| `spreadsheetTheme` | [SpreadsheetTheme](#spreadsheettheme) | Theme applied to the spreadsheet. |
| `timeZone` | `string` | The time zone of the spreadsheet, in CLDR format such as `America/New_York`. If the time zone isn't recognized, this may be a custom time zone such as `GMT-07:00`. |
| `iterativeCalculationSettings` | [IterativeCalculationSettings](#iterativecalculationsettings) | Determines whether and how circular references are resolved with iterative calculation. Absence of this field means that circular references result in calculation errors. |
## CellFormat
The format of a cell.
| Field | Type | Description |
| ---------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hyperlinkDisplayType` | [CellFormatHyperlinkDisplayType](#cellformathyperlinkdisplaytype) | If one exists, how a hyperlink should be displayed in the cell. |
| `textDirection` | [CellFormatTextDirection](#cellformattextdirection) | The direction of the text in the cell. |
| `padding` | [Padding](#padding) | The padding of the cell. |
| `backgroundColorStyle` | [ColorStyle](#colorstyle) | The background color of the cell. If background\_color is also set, this field takes precedence. |
| `horizontalAlignment` | [HorizontalAlign](#horizontalalign) | The horizontal alignment of the value in the cell. |
| `borders` | [Borders](#borders) | The borders of the cell. |
| `verticalAlignment` | [VerticalAlign](#verticalalign) | The vertical alignment of the value in the cell. |
| `textRotation` | [TextRotation](#textrotation) | The rotation applied to text in the cell. |
| `numberFormat` | [NumberFormat](#numberformat) | A format describing how number values should be represented to the user. |
| `wrapStrategy` | [WrapStrategy](#wrapstrategy) | The wrap strategy for the value in the cell. |
| `textFormat` | [TextFormat](#textformat) | The format of the text in the cell (unless overridden by a format run). Setting a cell-level link here clears the cell's existing links. Setting the link field in a TextFormatRun takes precedence over the cell-level link. |
## Padding
The amount of padding around the cell, in pixels. When updating padding, every field must be specified.
| Field | Type | Description |
| -------- | --------- | ------------------------------- |
| `right` | `integer` | The right padding of the cell. |
| `left` | `integer` | The left padding of the cell. |
| `bottom` | `integer` | The bottom padding of the cell. |
| `top` | `integer` | The top padding of the cell. |
## ColorStyle
A color value.
| Field | Type | Description |
| ------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `themeColor` | [ThemeColorType](#themecolortype) | Theme color. |
| `rgbColor` | [Color](#color) | RGB color. The [`alpha`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/other#Color.FIELDS.alpha) value in the [`Color`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/other#color) object isn't generally supported. |
## Color
Represents a color in the RGBA color space. This representation is designed for simplicity of conversion to and from color representations in various languages over compactness. For example, the fields of this representation can be trivially provided to the constructor of `java.awt.Color` in Java; it can also be trivially provided to UIColor's `+colorWithRed:green:blue:alpha` method in iOS; and, with just a little work, it can be easily formatted into a CSS `rgba()` string in JavaScript. This reference page doesn't have information about the absolute color space that should be used to interpret the RGB value—for example, sRGB, Adobe RGB, DCI-P3, and BT.2020. By default, applications should assume the sRGB color space. When color equality needs to be decided, implementations, unless documented otherwise, treat two colors as equal if all their red, green, blue, and alpha values each differ by at most `1e-5`. Example (Java): import com.google.type.Color; // ... public static java.awt.Color fromProto(Color protocolor) \{ float alpha = protocolor.hasAlpha() ? protocolor.getAlpha().getValue() : 1.0; return new java.awt.Color( protocolor.getRed(), protocolor.getGreen(), protocolor.getBlue(), alpha); } public static Color toProto(java.awt.Color color) \{ float red = (float) color.getRed(); float green = (float) color.getGreen(); float blue = (float) color.getBlue(); float denominator = 255.0; Color.Builder resultBuilder = Color .newBuilder() .setRed(red / denominator) .setGreen(green / denominator) .setBlue(blue / denominator); int alpha = color.getAlpha(); if (alpha != 255) \{ result.setAlpha( FloatValue .newBuilder() .setValue(((float) alpha) / denominator) .build()); } return resultBuilder.build(); } // ... Example (iOS / Obj-C): // ... static UIColor\* fromProto(Color\* protocolor) \{ float red = \[protocolor red]; float green = \[protocolor green]; float blue = \[protocolor blue]; FloatValue\* alpha\_wrapper = \[protocolor alpha]; float alpha = 1.0; if (alpha\_wrapper != nil) \{ alpha = \[alpha\_wrapper value]; } return \[UIColor colorWithRed:red green:green blue:blue alpha:alpha]; } static Color\* toProto(UIColor\* color) \{ CGFloat red, green, blue, alpha; if (!\[color getRed:\&red green:\&green blue:\&blue alpha:\&alpha]) \{ return nil; } Color\* result = \[\[Color alloc] init]; \[result setRed:red]; \[result setGreen:green]; \[result setBlue:blue]; if (alpha \<= 0.9999) \{ \[result setAlpha:floatWrapperWithValue(alpha)]; } \[result autorelease]; return result; } // ... Example (JavaScript): // ... var protoToCssColor = function(rgb\_color) \{ var redFrac = rgb\_color.red || 0.0; var greenFrac = rgb\_color.green || 0.0; var blueFrac = rgb\_color.blue || 0.0; var red = Math.floor(redFrac \* 255); var green = Math.floor(greenFrac \* 255); var blue = Math.floor(blueFrac \* 255); if (!('alpha' in rgb\_color)) \{ return rgbToCssColor(red, green, blue); } var alphaFrac = rgb\_color.alpha.value || 0.0; var rgbParams = \[red, green, blue].join(','); return \['rgba(', rgbParams, ',', alphaFrac, ')'].join(''); }; var rgbToCssColor = function(red, green, blue) \{ var rgbNumber = new Number((red \<\< 16) | (green \<\< 8) | blue); var hexString = rgbNumber.toString(16); var missingZeros = 6 - hexString.length; var resultBuilder = \['#']; for (var i = 0; i \< missingZeros; i++) \{ resultBuilder.push('0'); } resultBuilder.push(hexString); return resultBuilder.join(''); }; // ...
| Field | Type | Description |
| ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `green` | `number` | The amount of green in the color as a value in the interval \[0, 1]. |
| `blue` | `number` | The amount of blue in the color as a value in the interval \[0, 1]. |
| `alpha` | `number` | The fraction of this color that should be applied to the pixel. That is, the final pixel color is defined by the equation: `pixel color = alpha * (this color) + (1.0 - alpha) * (background color)` This means that a value of 1.0 corresponds to a solid color, whereas a value of 0.0 corresponds to a completely transparent color. This uses a wrapper message rather than a simple float scalar so that it is possible to distinguish between a default value and the value being unset. If omitted, this color object is rendered as a solid color (as if the alpha value had been explicitly given a value of 1.0). |
| `red` | `number` | The amount of red in the color as a value in the interval \[0, 1]. |
## Borders
The borders of the cell.
| Field | Type | Description |
| -------- | ----------------- | ------------------------------ |
| `left` | [Border](#border) | The left border of the cell. |
| `bottom` | [Border](#border) | The bottom border of the cell. |
| `top` | [Border](#border) | The top border of the cell. |
| `right` | [Border](#border) | The right border of the cell. |
## Border
A border along a cell.
| Field | Type | Description |
| ------------ | --------------------------- | --------------------------------------------------------------------------- |
| `colorStyle` | [ColorStyle](#colorstyle) | The color of the border. If color is also set, this field takes precedence. |
| `style` | [BorderStyle](#borderstyle) | The style of the border. |
## TextRotation
The rotation applied to text in a cell.
| Field | Type | Description |
| ---------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `angle` | `integer` | The angle between the standard orientation and the desired orientation. Measured in degrees. Valid values are between -90 and 90. Positive angles are angled upwards, negative are angled downwards. Note: For LTR text direction positive angles are in the counterclockwise direction, whereas for RTL they are in the clockwise direction |
| `vertical` | `boolean` | If true, text reads top to bottom, but the orientation of individual characters is unchanged. For example: \| V \| \| e \| \| r \| \| t \| \| i \| \| c \| \| a \| \| l \| |
## NumberFormat
The number format of a cell.
| Field | Type | Description |
| --------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pattern` | `string` | Pattern string used for formatting. If not set, a default pattern based on the spreadsheet's locale will be used if necessary for the given type. See the [Date and Number Formats guide](https://developers.google.com/workspace/sheets/api/guides/formats) for more information about the supported patterns. |
| `type` | [NumberFormatType](#numberformattype) | The type of the number format. When writing, this field must be set. |
## TextFormat
The format of a run of text in a cell. Absent values indicate that the field isn't specified.
| Field | Type | Description |
| ---------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fontFamily` | `string` | The font family. |
| `strikethrough` | `boolean` | True if the text has a strikethrough. |
| `underline` | `boolean` | True if the text is underlined. |
| `foregroundColorStyle` | [ColorStyle](#colorstyle) | The foreground color of the text. If foreground\_color is also set, this field takes precedence. |
| `bold` | `boolean` | True if the text is bold. |
| `fontSize` | `integer` | The size of the font. |
| `italic` | `boolean` | True if the text is italicized. |
| `link` | [Link](#link) | The link destination of the text, if any. Setting the link field in a TextFormatRun will clear the cell's existing links or a cell-level link set in the same request. When a link is set, the text foreground color will be set to the default link color and the text will be underlined. If these fields are modified in the same request, those values will be used instead of the link defaults. |
## Link
An external or local reference.
| Field | Type | Description |
| ----- | -------- | -------------------- |
| `uri` | `string` | The link identifier. |
## SpreadsheetTheme
Represents spreadsheet theme
| Field | Type | Description |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `themeColors` | [ThemeColorPair](#themecolorpair)\[] | The spreadsheet theme color pairs. To update you must provide all theme color pairs. |
| `primaryFontFamily` | `string` | Name of the primary font family. |
## ThemeColorPair
A pair mapping a spreadsheet theme color type to the concrete color it represents.
| Field | Type | Description |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `color` | [ColorStyle](#colorstyle) | The concrete color corresponding to the theme color type. |
| `colorType` | [ThemeColorType](#themecolortype) | The type of the spreadsheet theme color. |
## IterativeCalculationSettings
Settings to control how circular dependencies are resolved with iterative calculation.
| Field | Type | Description |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `convergenceThreshold` | `number` | When iterative calculation is enabled and successive results differ by less than this threshold value, the calculation rounds stop. |
| `maxIterations` | `integer` | When iterative calculation is enabled, the maximum number of calculation rounds to perform. |
## Sheet
A sheet in a spreadsheet.
| Field | Type | Description |
| -------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rowGroups` | [DimensionGroup](#dimensiongroup)\[] | All row groups on this sheet, ordered by increasing range start index, then by group depth. |
| `slicers` | [Slicer](#slicer)\[] | The slicers on this sheet. |
| `tables` | [Table](#table)\[] | The tables on this sheet. |
| `conditionalFormats` | [ConditionalFormatRule](#conditionalformatrule)\[] | The conditional format rules in this sheet. |
| `basicFilter` | [BasicFilter](#basicfilter) | The filter on this sheet, if any. |
| `merges` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange)\[] | The ranges that are merged together. |
| `columnGroups` | [DimensionGroup](#dimensiongroup)\[] | All column groups on this sheet, ordered by increasing range start index, then by group depth. |
| `properties` | [SheetProperties](#sheetproperties) | The properties of the sheet. |
| `bandedRanges` | [BandedRange](#bandedrange)\[] | The banded (alternating colors) ranges on this sheet. |
| `developerMetadata` | [DeveloperMetadata](#developermetadata)\[] | The developer metadata associated with a sheet. |
| `data` | [GridData](#griddata)\[] | Data in the grid, if this is a grid sheet. The number of GridData objects returned is dependent on the number of ranges requested on this sheet. For example, if this is representing `Sheet1`, and the spreadsheet was requested with ranges `Sheet1!A1:C10` and `Sheet1!D15:E20`, then the first GridData will have a startRow/startColumn of `0`, while the second one will have `startRow 14` (zero-based row 15), and `startColumn 3` (zero-based column D). For a DATA\_SOURCE sheet, you can not request a specific range, the GridData contains all the values. |
| `charts` | [EmbeddedChart](#embeddedchart)\[] | The specifications of every chart on this sheet. |
| `filterViews` | [FilterView](#filterview)\[] | The filter views in this sheet. |
| `protectedRanges` | [ProtectedRange](#protectedrange)\[] | The protected ranges in this sheet. |
| `commentAnchors` | [CommentAnchor](#commentanchor)\[] | The comment anchors on this sheet. Developer Preview. |
## DimensionGroup
A group over an interval of rows or columns on a sheet, which can contain or be contained within other groups. A group can be collapsed or expanded as a unit on the sheet.
| Field | Type | Description |
| ----------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `depth` | `integer` | The depth of the group, representing how many groups have a range that wholly contains the range of this group. |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The range over which this group exists. |
| `collapsed` | `boolean` | This field is true if this group is collapsed. A collapsed group remains collapsed if an overlapping group at a shallower depth is expanded. A true value does not imply that all dimensions within the group are hidden, since a dimension's visibility can change independently from this group property. However, when this property is updated, all dimensions within it are set to hidden if this field is true, or set to visible if this field is false. |
## Slicer
A slicer in a sheet.
| Field | Type | Description |
| ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec` | [SlicerSpec](#slicerspec) | The specification of the slicer. |
| `slicerId` | `integer` | The ID of the slicer. |
| `position` | [EmbeddedObjectPosition](#embeddedobjectposition) | The position of the slicer. Note that slicer can be positioned only on existing sheet. Also, width and height of slicer can be automatically adjusted to keep it within permitted limits. |
## SlicerSpec
The specifications of a slicer.
| Field | Type | Description |
| ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `dataRange` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The data range of the slicer. |
| `title` | `string` | The title of the slicer. |
| `textFormat` | [TextFormat](#textformat) | The text format of title in the slicer. The link field is not supported. |
| `columnIndex` | `integer` | The zero-based column index in the data table on which the filter is applied to. |
| `filterCriteria` | [FilterCriteria](#filtercriteria) | The filtering criteria of the slicer. |
| `horizontalAlignment` | [HorizontalAlign](#horizontalalign) | The horizontal alignment of title in the slicer. If unspecified, defaults to `LEFT` |
| `backgroundColorStyle` | [ColorStyle](#colorstyle) | The background color of the slicer. If background\_color is also set, this field takes precedence. |
| `applyToPivotTables` | `boolean` | True if the filter should apply to pivot tables. If not set, default to `True`. |
## FilterCriteria
Criteria for showing or hiding rows in a filter or filter view.
| Field | Type | Description |
| ----------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibleBackgroundColorStyle` | [ColorStyle](#colorstyle) | The background fill color to filter by; only cells with this fill color are shown. This field is mutually exclusive with visible\_foreground\_color, and must be set to an RGB-type color. If visible\_background\_color is also set, this field takes precedence. |
| `hiddenValues` | `string`\[] | Values that should be hidden. |
| `visibleForegroundColorStyle` | [ColorStyle](#colorstyle) | The foreground color to filter by; only cells with this foreground color are shown. This field is mutually exclusive with visible\_background\_color, and must be set to an RGB-type color. If visible\_foreground\_color is also set, this field takes precedence. |
| `condition` | [BooleanCondition](#booleancondition) | A condition that must be `true` for values to be shown. (This does not override hidden\_values -- if a value is listed there, it will still be hidden.) |
## BooleanCondition
A condition that can evaluate to true or false. BooleanConditions are used by conditional formatting, data validation, and the criteria in filters.
| Field | Type | Description |
| -------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `values` | [ConditionValue](#conditionvalue)\[] | The values of the condition. The number of supported values depends on the condition type. Some support zero values, others one or two values, and ConditionType.ONE\_OF\_LIST supports an arbitrary number of values. |
| `type` | [BooleanConditionType](#booleanconditiontype) | The type of condition. |
## ConditionValue
The value of the condition.
| Field | Type | Description |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userEnteredValue` | `string` | A value the condition is based on. The value is parsed as if the user typed into a cell. Formulas are supported (and must begin with an `=` or a '+'). |
| `relativeDate` | [ConditionValueRelativeDate](#conditionvaluerelativedate) | A relative date (based on the current date). Valid only if the type is DATE\_BEFORE, DATE\_AFTER, DATE\_ON\_OR\_BEFORE or DATE\_ON\_OR\_AFTER. Relative dates are not supported in data validation. They are supported only in conditional formatting and conditional filters. |
## EmbeddedObjectPosition
The position of an embedded object such as a chart.
| Field | Type | Description |
| ----------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `overlayPosition` | [OverlayPosition](#overlayposition) | The position at which the object is overlaid on top of a grid. |
| `sheetId` | `integer` | The sheet this is on. Set only if the embedded object is on its own sheet. Must be non-negative. ≥ 0 |
| `newSheet` | `boolean` | If true, the embedded object is put on a new sheet whose ID is chosen for you. Used only when writing. |
## OverlayPosition
The location an object is overlaid on top of a grid.
| Field | Type | Description |
| --------------- | --------------------------------- | --------------------------------------------------------------------------------- |
| `offsetYPixels` | `integer` | The vertical offset, in pixels, that the object is offset from the anchor cell. |
| `heightPixels` | `integer` | The height of the object, in pixels. Defaults to 371. |
| `anchorCell` | [GridCoordinate](#gridcoordinate) | The cell the object is anchored to. |
| `widthPixels` | `integer` | The width of the object, in pixels. Defaults to 600. |
| `offsetXPixels` | `integer` | The horizontal offset, in pixels, that the object is offset from the anchor cell. |
## GridCoordinate
A coordinate in a sheet. All indexes are zero-based.
| Field | Type | Description |
| ------------- | --------- | ----------------------------------- |
| `columnIndex` | `integer` | The column index of the coordinate. |
| `sheetId` | `integer` | The sheet this coordinate is on. |
| `rowIndex` | `integer` | The row index of the coordinate. |
## Table
A table.
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| `name` | `string` | The table name. This is unique to all tables in the same spreadsheet. |
| `rowsProperties` | [TableRowsProperties](#tablerowsproperties) | The table rows properties. |
| `tableId` | `string` | The id of the table. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The table range. |
| `columnProperties` | [TableColumnProperties](#tablecolumnproperties)\[] | The table column properties. |
## TableRowsProperties
The table row properties.
| Field | Type | Description |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `footerColorStyle` | [ColorStyle](#colorstyle) | The color of the last row. If this field is not set a footer is not added, the last row is filled with either first\_band\_color\_style or second\_band\_color\_style, depending on the color of the previous row. If updating an existing table without a footer to have a footer, the range will be expanded by 1 row. If updating an existing table with a footer and removing a footer, the range will be shrunk by 1 row. |
| `headerColorStyle` | [ColorStyle](#colorstyle) | The color of the header row. If this field is set, the header row is filled with the specified color. Otherwise, the header row is filled with a default color. |
| `firstBandColorStyle` | [ColorStyle](#colorstyle) | The first color that is alternating. If this field is set, the first banded row is filled with the specified color. Otherwise, the first banded row is filled with a default color. |
| `secondBandColorStyle` | [ColorStyle](#colorstyle) | The second color that is alternating. If this field is set, the second banded row is filled with the specified color. Otherwise, the second banded row is filled with a default color. |
## TableColumnProperties
The table column.
| Field | Type | Description |
| -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnName` | `string` | The column name. |
| `dataValidationRule` | [TableColumnDataValidationRule](#tablecolumndatavalidationrule) | The column data validation rule. Only set for dropdown column type. |
| `columnType` | [TableColumnPropertiesColumnType](#tablecolumnpropertiescolumntype) | The column type. |
| `columnIndex` | `integer` | The 0-based column index. This index is relative to its position in the table and is not necessarily the same as the column index in the sheet. |
## TableColumnDataValidationRule
A data validation rule for a column in a table.
| Field | Type | Description |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `condition` | [BooleanCondition](#booleancondition) | The condition that data in the cell must match. Valid only if the \[BooleanCondition.type] is ONE\_OF\_LIST. |
## ConditionalFormatRule
A rule describing a conditional format.
| Field | Type | Description |
| -------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `ranges` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange)\[] | The ranges that are formatted if the condition is true. All the ranges must be on the same grid. |
| `booleanRule` | [BooleanRule](#booleanrule) | The formatting is either "on" or "off" according to the rule. |
| `gradientRule` | [GradientRule](#gradientrule) | The formatting will vary based on the gradients in the rule. |
## BooleanRule
A rule that may or may not match, depending on the condition.
| Field | Type | Description |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format` | [CellFormat](#cellformat) | The format to apply. Conditional formatting can only apply a subset of formatting: bold, italic, strikethrough, foreground color and, background color. |
| `condition` | [BooleanCondition](#booleancondition) | The condition of the rule. If the condition evaluates to true, the format is applied. |
## GradientRule
A rule that applies a gradient color scale format, based on the interpolation points listed. The format of a cell will vary based on its contents as compared to the values of the interpolation points.
| Field | Type | Description |
| ---------- | ----------------------------------------- | --------------------------------------- |
| `midpoint` | [InterpolationPoint](#interpolationpoint) | An optional midway interpolation point. |
| `minpoint` | [InterpolationPoint](#interpolationpoint) | The starting interpolation point. |
| `maxpoint` | [InterpolationPoint](#interpolationpoint) | The final interpolation point. |
## InterpolationPoint
A single interpolation point on a gradient conditional format. These pin the gradient color scale according to the color, type and value chosen.
| Field | Type | Description |
| ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `type` | [InterpolationPointType](#interpolationpointtype) | How the value should be interpreted. |
| `colorStyle` | [ColorStyle](#colorstyle) | The color this interpolation point should use. If color is also set, this field takes precedence. |
| `value` | `string` | The value this interpolation point uses. May be a formula. Unused if type is MIN or MAX. |
## BasicFilter
The default filter associated with a sheet. For more information, see [Manage data visibility with filters](https://developers.google.com/workspace/sheets/api/guides/filters).
| Field | Type | Description |
| ------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableId` | `string` | The table this filter is backed by, if any. When writing, only one of range or table\_id may be set. |
| `sortSpecs` | [SortSpec](#sortspec)\[] | The sort order per column. Later specifications are used when values are equal in the earlier specifications. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range the filter covers. |
| `filterSpecs` | [FilterSpec](#filterspec)\[] | The filter criteria per column. Both criteria and filter\_specs are populated in responses. If both fields are specified in an update request, this field takes precedence. |
## SortSpec
A sort order associated with a specific column or row.
| Field | Type | Description |
| --------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sortOrder` | [SortOrder](#sortorder) | The order data should be sorted. |
| `dataSourceColumnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | Reference to a data source column. |
| `backgroundColorStyle` | [ColorStyle](#colorstyle) | The background fill color to sort by; cells with this fill color are sorted to the top. Mutually exclusive with foreground\_color, and must be an RGB-type color. If background\_color is also set, this field takes precedence. |
| `dimensionIndex` | `integer` | The dimension the sort should be applied to. |
| `foregroundColorStyle` | [ColorStyle](#colorstyle) | The foreground color to sort by; cells with this foreground color are sorted to the top. Mutually exclusive with background\_color, and must be an RGB-type color. If foreground\_color is also set, this field takes precedence. |
## DataSourceColumnReference
An unique identifier that references a data source column.
| Field | Type | Description |
| ------ | -------- | ------------------------------------------------------------------------- |
| `name` | `string` | The display name of the column. It should be unique within a data source. |
## FilterSpec
The filter criteria associated with a specific column.
| Field | Type | Description |
| --------------------------- | ------------------------------------------------------- | ---------------------------------- |
| `filterCriteria` | [FilterCriteria](#filtercriteria) | The criteria for the column. |
| `columnIndex` | `integer` | The zero-based column index. |
| `dataSourceColumnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | Reference to a data source column. |
## SheetProperties
Properties of a sheet.
| Field | Type | Description |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | `string` | The name of the sheet. |
| `hidden` | `boolean` | True if the sheet is hidden in the UI, false if it's visible. |
| `rightToLeft` | `boolean` | True if the sheet is an RTL sheet instead of an LTR sheet. |
| `gridProperties` | [GridProperties](#gridproperties) | Additional properties of the sheet if this sheet is a grid. (If the sheet is an object sheet, containing a chart or image, then this field will be absent.) When writing it is an error to set any grid properties on non-grid sheets. If this sheet is a DATA\_SOURCE sheet, this field is output only but contains the properties that reflect how a data source sheet is rendered in the UI, e.g. row\_count. |
| `sheetId` | `integer` | The ID of the sheet. Must be non-negative. This field cannot be changed once set. ≥ 0 |
| `sheetType` | [SheetType](#sheettype) | The type of sheet. Defaults to GRID. This field cannot be changed once set. |
| `tabColorStyle` | [ColorStyle](#colorstyle) | The color of the tab in the UI. If tab\_color is also set, this field takes precedence. |
| `index` | `integer` | The index of the sheet within the spreadsheet. When adding or updating sheet properties, if this field is excluded then the sheet is added or moved to the end of the sheet list. When updating sheet indices or inserting sheets, movement is considered in "before the move" indexes. For example, if there were three sheets (S1, S2, S3) in order to move S1 ahead of S2 the index would have to be set to 2. A sheet index update request is ignored if the requested index is identical to the sheets current index or if the requested new index is equal to the current sheet index + 1. |
## GridProperties
Properties of a grid.
| Field | Type | Description |
| ------------------------- | --------- | -------------------------------------------------------------------- |
| `frozenRowCount` | `integer` | The number of rows that are frozen in the grid. |
| `rowGroupControlAfter` | `boolean` | True if the row grouping control toggle is shown after the group. |
| `columnCount` | `integer` | The number of columns in the grid. |
| `columnGroupControlAfter` | `boolean` | True if the column grouping control toggle is shown after the group. |
| `frozenColumnCount` | `integer` | The number of columns that are frozen in the grid. |
| `rowCount` | `integer` | The number of rows in the grid. |
| `hideGridlines` | `boolean` | True if the grid isn't showing gridlines in the UI. |
## DataSourceColumn
A column in a data source.
| Field | Type | Description |
| ----------- | ------------------------------------------------------- | ------------------------------------- |
| `formula` | `string` | The formula of the calculated column. |
| `reference` | [DataSourceColumnReference](#datasourcecolumnreference) | The column reference. |
## BandedRange
A banded (alternating colors) range in a sheet.
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnProperties` | [BandingProperties](#bandingproperties) | Properties for column bands. These properties are applied on a column- by-column basis throughout all the columns in the range. At least one of row\_properties or column\_properties must be specified. |
| `rowProperties` | [BandingProperties](#bandingproperties) | Properties for row bands. These properties are applied on a row-by-row basis throughout all the rows in the range. At least one of row\_properties or column\_properties must be specified. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range over which these properties are applied. |
| `bandedRangeId` | `integer` | The ID of the banded range. If unset, refer to banded\_range\_reference. |
## BandingProperties
Properties referring a single dimension (either row or column). If both BandedRange.row\_properties and BandedRange.column\_properties are set, the fill colors are applied to cells according to the following rules: \* header\_color and footer\_color take priority over band colors. \* first\_band\_color takes priority over second\_band\_color. \* row\_properties takes priority over column\_properties. For example, the first row color takes priority over the first column color, but the first column color takes priority over the second row color. Similarly, the row header takes priority over the column header in the top left cell, but the column header takes priority over the first row color if the row header is not set.
| Field | Type | Description |
| ---------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstBandColorStyle` | [ColorStyle](#colorstyle) | The first color that is alternating. (Required) If first\_band\_color is also set, this field takes precedence. |
| `footerColorStyle` | [ColorStyle](#colorstyle) | The color of the last row or column. If this field is not set, the last row or column is filled with either first\_band\_color or second\_band\_color, depending on the color of the previous row or column. If footer\_color is also set, this field takes precedence. |
| `headerColorStyle` | [ColorStyle](#colorstyle) | The color of the first row or column. If this field is set, the first row or column is filled with this color and the colors alternate between first\_band\_color and second\_band\_color starting from the second row or column. Otherwise, the first row or column is filled with first\_band\_color and the colors proceed to alternate as they normally would. If header\_color is also set, this field takes precedence. |
| `secondBandColorStyle` | [ColorStyle](#colorstyle) | The second color that is alternating. (Required) If second\_band\_color is also set, this field takes precedence. |
## DeveloperMetadata
Developer metadata associated with a location or object in a spreadsheet. For more information, see [Read, write, and search metadata](https://developers.google.com/workspace/sheets/api/guides/metadata). Developer metadata may be used to associate arbitrary data with various parts of a spreadsheet and it will remain associated at those locations as they move around and the spreadsheet is edited. For example, if developer metadata is associated with row 5 and another row is then subsequently inserted above row 5, that original metadata is still associated with the row it was first associated with (what is now row 6). If the associated object is deleted then its metadata is deleted too.
| Field | Type | Description |
| --------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location` | [DeveloperMetadataLocation](/charter/charter/packs/gsheets/values/objects#developermetadatalocation) | The location where the metadata is associated. |
| `metadataId` | `integer` | The spreadsheet-scoped unique ID that identifies the metadata. IDs may be specified when metadata is created, otherwise one will be randomly generated and assigned. Must be positive. |
| `metadataKey` | `string` | The metadata key. There may be multiple metadata in a spreadsheet with the same key. Developer metadata must always have a key specified. |
| `visibility` | [DeveloperMetadataVisibility](/charter/charter/packs/gsheets/values/objects#developermetadatavisibility) | The metadata visibility. Developer metadata must always have visibility specified. |
| `metadataValue` | `string` | Data associated with the metadata's key. |
## GridData
Data in the grid, as well as metadata about the dimensions.
| Field | Type | Description |
| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rowMetadata` | [DimensionProperties](#dimensionproperties)\[] | Metadata about the requested rows in the grid, starting with the row in start\_row. |
| `startColumn` | `integer` | The first column this GridData refers to, zero-based. |
| `rowData` | [RowData](#rowdata)\[] | The data in the grid, one entry per row, starting with the row in startRow. The values in RowData will correspond to columns starting at start\_column. |
| `columnMetadata` | [DimensionProperties](#dimensionproperties)\[] | Metadata about the requested columns in the grid, starting with the column in start\_column. |
| `startRow` | `integer` | The first row this GridData refers to, zero-based. |
## DimensionProperties
Properties about a dimension.
| Field | Type | Description |
| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `pixelSize` | `integer` | The height (if a row) or width (if a column) of the dimension in pixels. |
| `developerMetadata` | [DeveloperMetadata](#developermetadata)\[] | The developer metadata associated with a single row or column. |
| `hiddenByUser` | `boolean` | True if this dimension is explicitly hidden. |
## RowData
Data about each cell in a row.
| Field | Type | Description |
| -------- | ------------------------ | -------------------------------------- |
| `values` | [CellData](#celldata)\[] | The values in the row, one per column. |
## CellData
Data about a specific cell.
| Field | Type | Description |
| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dataSourceTable` | [DataSourceTable](#datasourcetable) | A data source table anchored at this cell. The size of data source table itself is computed dynamically based on its configuration. Only the first cell of the data source table contains the data source table definition. The other cells will contain the display values of the data source table result in their effective\_value fields. |
| `dataValidation` | [DataValidationRule](#datavalidationrule) | A data validation rule on the cell, if any. When writing, the new data validation rule will overwrite any prior rule. |
| `chipRuns` | [ChipRun](#chiprun)\[] | Optional. Runs of chips applied to subsections of the cell. Properties of a run start at a specific index in the text and continue until the next run. When reading, all chipped and non-chipped runs are included. Non-chipped runs will have an empty Chip. When writing, only runs with chips are included. Runs containing chips are of length 1 and are represented in the user-entered text by an “@” placeholder symbol. New runs will overwrite any prior runs. Writing a new user\_entered\_value will erase previous runs. |
| `pivotTable` | [PivotTable](#pivottable) | A pivot table anchored at this cell. The size of pivot table itself is computed dynamically based on its data, grouping, filters, values, etc. Only the top-left cell of the pivot table contains the pivot table definition. The other cells will contain the calculated values of the results of the pivot in their effective\_value fields. |
| `textFormatRuns` | [TextFormatRun](#textformatrun)\[] | Runs of rich text applied to subsections of the cell. Runs are only valid on user entered strings, not formulas, bools, or numbers. Properties of a run start at a specific index in the text and continue until the next run. Runs will inherit the properties of the cell unless explicitly changed. When writing, the new runs will overwrite any prior runs. When writing a new user\_entered\_value, previous runs are erased. |
| `userEnteredFormat` | [CellFormat](#cellformat) | The format the user entered for the cell. When writing, the new format will be merged with the existing format. |
| `userEnteredValue` | [ExtendedValue](#extendedvalue) | The value the user entered in the cell. e.g., `1234`, `'Hello'`, or `=NOW()` Note: Dates, Times and DateTimes are represented as doubles in serial number format. |
| `note` | `string` | Any note on the cell. |
## DataSourceTable
A data source table, which allows the user to import a static table of data from the DataSource into Sheets. This is also known as "Extract" in the Sheets editor.
| Field | Type | Description |
| --------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `columns` | [DataSourceColumnReference](#datasourcecolumnreference)\[] | Columns selected for the data source table. The column\_selection\_type must be SELECTED. |
| `dataSourceId` | `string` | The ID of the data source the data source table is associated with. |
| `rowLimit` | `integer` | The limit of rows to return. If not set, a default limit is applied. Please refer to the Sheets editor for the default and max limit. |
| `sortSpecs` | [SortSpec](#sortspec)\[] | Sort specifications in the data source table. The result of the data source table is sorted based on the sort specifications in order. |
| `columnSelectionType` | [DataSourceTableColumnSelectionType](#datasourcetablecolumnselectiontype) | The type to select columns for the data source table. Defaults to SELECTED. |
| `filterSpecs` | [FilterSpec](#filterspec)\[] | Filter specifications in the data source table. |
## DataValidationRule
A data validation rule.
| Field | Type | Description |
| -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `showCustomUi` | `boolean` | True if the UI should be customized based on the kind of condition. If true, "List" conditions will show a dropdown. |
| `inputMessage` | `string` | A message to show the user when adding data to the cell. |
| `condition` | [BooleanCondition](#booleancondition) | The condition that data in the cell must match. |
| `strict` | `boolean` | True if invalid data should be rejected. |
## ChipRun
The run of a chip. The chip continues until the start index of the next run.
| Field | Type | Description |
| ------------ | ------------- | ------------------------------------------------------------------------------------- |
| `startIndex` | `integer` | Required. The zero-based character index where this run starts, in UTF-16 code units. |
| `chip` | [Chip](#chip) | Optional. The chip of this run. |
## Chip
The Smart Chip.
| Field | Type | Description |
| -------------------- | ----------------------------------------- | ------------------------------ |
| `richLinkProperties` | [RichLinkProperties](#richlinkproperties) | Properties of a rich link. |
| `personProperties` | [PersonProperties](#personproperties) | Properties of a linked person. |
## RichLinkProperties
Properties of a link to a Google resource (such as a file in Drive, a YouTube video, a Maps address, or a Calendar event). Only Drive files can be written as chips. All other rich link types are read only. URIs cannot exceed 2000 bytes when writing. NOTE: Writing Drive file chips requires at least one of the `drive.file`, `drive.readonly`, or `drive` OAuth scopes.
| Field | Type | Description |
| ----- | -------- | ------------------------------------------------------ |
| `uri` | `string` | Required. The URI to the link. This is always present. |
## PersonProperties
Properties specific to a linked person.
| Field | Type | Description |
| --------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `email` | `string` | Required. The email address linked to this person. This field is always present. |
| `displayFormat` | [PersonPropertiesDisplayFormat](#personpropertiesdisplayformat) | Optional. The display format of the person chip. If not set, the default display format is used. |
## PivotTable
A pivot table.
| Field | Type | Description |
| -------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filterSpecs` | [PivotFilterSpec](#pivotfilterspec)\[] | The filters applied to the source columns before aggregating data for the pivot table. Both criteria and filter\_specs are populated in responses. If both fields are specified in an update request, this field takes precedence. |
| `source` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range the pivot table is reading data from. |
| `values` | [PivotValue](#pivotvalue)\[] | A list of values to include in the pivot table. |
| `dataSourceId` | `string` | The ID of the data source the pivot table is reading data from. |
| `valueLayout` | [PivotTableValueLayout](#pivottablevaluelayout) | Whether values should be listed horizontally (as columns) or vertically (as rows). |
| `rows` | [PivotGroup](#pivotgroup)\[] | Each row grouping in the pivot table. |
| `columns` | [PivotGroup](#pivotgroup)\[] | Each column grouping in the pivot table. |
## PivotFilterSpec
The pivot table filter criteria associated with a specific source column offset.
| Field | Type | Description |
| --------------------------- | ------------------------------------------------------- | ------------------------------------------------- |
| `dataSourceColumnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | The reference to the data source column. |
| `filterCriteria` | [PivotFilterCriteria](#pivotfiltercriteria) | The criteria for the column. |
| `columnOffsetIndex` | `integer` | The zero-based column offset of the source range. |
## PivotFilterCriteria
Criteria for showing/hiding rows in a pivot table.
| Field | Type | Description |
| ------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibleByDefault` | `boolean` | Whether values are visible by default. If true, the visible\_values are ignored, all values that meet condition (if specified) are shown. If false, values that are both in visible\_values and meet condition are shown. |
| `visibleValues` | `string`\[] | Values that should be included. Values not listed here are excluded. |
| `condition` | [BooleanCondition](#booleancondition) | A condition that must be true for values to be shown. (`visibleValues` does not override this -- even if a value is listed there, it is still hidden if it does not meet the condition.) Condition values that refer to ranges in A1-notation are evaluated relative to the pivot table sheet. References are treated absolutely, so are not filled down the pivot table. For example, a condition value of `=A1` on "Pivot Table 1" is treated as `'Pivot Table 1'!$A$1`. The source data of the pivot table can be referenced by column header name. For example, if the source data has columns named "Revenue" and "Cost" and a condition is applied to the "Revenue" column with type `NUMBER_GREATER` and value `=Cost`, then only columns where "Revenue" > "Cost" are included. |
## PivotValue
The definition of how a value in a pivot table should be calculated.
| Field | Type | Description |
| --------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataSourceColumnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | The reference to the data source column that this value reads from. |
| `calculatedDisplayType` | [PivotValueCalculatedDisplayType](#pivotvaluecalculateddisplaytype) | If specified, indicates that pivot values should be displayed as the result of a calculation with another pivot value. For example, if calculated\_display\_type is specified as PERCENT\_OF\_GRAND\_TOTAL, all the pivot values are displayed as the percentage of the grand total. In the Sheets editor, this is referred to as "Show As" in the value section of a pivot table. |
| `name` | `string` | A name to use for the value. |
| `summarizeFunction` | [PivotValueSummarizeFunction](#pivotvaluesummarizefunction) | A function to summarize the value. If formula is set, the only supported values are SUM and CUSTOM. If sourceColumnOffset is set, then `CUSTOM` is not supported. |
| `sourceColumnOffset` | `integer` | The column offset of the source range that this value reads from. For example, if the source was `C10:E15`, a `sourceColumnOffset` of `0` means this value refers to column `C`, whereas the offset `1` would refer to column `D`. |
| `formula` | `string` | A custom formula to calculate the value. The formula must start with an `=` character. |
## PivotGroup
A single grouping (either row or column) in a pivot table.
| Field | Type | Description |
| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showTotals` | `boolean` | True if the pivot table should include the totals for this grouping. |
| `label` | `string` | The labels to use for the row/column groups which can be customized. For example, in the following pivot table, the row label is `Region` (which could be renamed to `State`) and the column label is `Product` (which could be renamed `Item`). Pivot tables created before December 2017 do not have header labels. If you'd like to add header labels to an existing pivot table, please delete the existing pivot table and then create a new pivot table with same parameters. +--------------+---------+-------+ \| SUM of Units \| Product \| \| \| Region \| Pen \| Paper \| +--------------+---------+-------+ \| New York \| 345 \| 98 \| \| Oregon \| 234 \| 123 \| \| Tennessee \| 531 \| 415 \| +--------------+---------+-------+ \| Grand Total \| 1110 \| 636 \| +--------------+---------+-------+ |
| `sourceColumnOffset` | `integer` | The column offset of the source range that this grouping is based on. For example, if the source was `C10:E15`, a `sourceColumnOffset` of `0` means this group refers to column `C`, whereas the offset `1` would refer to column `D`. |
| `valueBucket` | [PivotGroupSortValueBucket](#pivotgroupsortvaluebucket) | The bucket of the opposite pivot group to sort by. If not specified, sorting is alphabetical by this group's values. |
| `repeatHeadings` | `boolean` | True if the headings in this pivot group should be repeated. This is only valid for row groupings and is ignored by columns. By default, we minimize repetition of headings by not showing higher level headings where they are the same. For example, even though the third row below corresponds to "Q1 Mar", "Q1" is not shown because it is redundant with previous rows. Setting repeat\_headings to true would cause "Q1" to be repeated for "Feb" and "Mar". +--------------+ \| Q1 \| Jan \| \| \| Feb \| \| \| Mar \| +--------+-----+ \| Q1 Total \| +--------------+ |
| `valueMetadata` | [PivotGroupValueMetadata](#pivotgroupvaluemetadata)\[] | Metadata about values in the grouping. |
| `groupRule` | [PivotGroupRule](#pivotgrouprule) | The group rule to apply to this row/column group. |
| `sortOrder` | [SortOrder](#sortorder) | The order the values in this group should be sorted. |
| `groupLimit` | [PivotGroupLimit](#pivotgrouplimit) | The count limit on rows or columns to apply to this pivot group. |
| `dataSourceColumnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | The reference to the data source column this grouping is based on. |
## PivotGroupSortValueBucket
Information about which values in a pivot group should be used for sorting.
| Field | Type | Description |
| ------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `valuesIndex` | `integer` | The offset in the PivotTable.values list which the values in this grouping should be sorted by. |
| `buckets` | [ExtendedValue](#extendedvalue)\[] | Determines the bucket from which values are chosen to sort. For example, in a pivot table with one row group & two column groups, the row group can list up to two values. The first value corresponds to a value within the first column group, and the second value corresponds to a value in the second column group. If no values are listed, this would indicate that the row should be sorted according to the "Grand Total" over the column groups. If a single value is listed, this would correspond to using the "Total" of that bucket. |
## ExtendedValue
The kinds of value that a cell in a spreadsheet can have.
| Field | Type | Description |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `numberValue` | `number` | Represents a double value. Note: Dates, Times and DateTimes are represented as doubles in SERIAL\_NUMBER format. |
| `stringValue` | `string` | Represents a string value. Leading single quotes are not included. For example, if the user typed `'123` into the UI, this would be represented as a `stringValue` of `"123"`. |
| `formulaValue` | `string` | Represents a formula. |
| `boolValue` | `boolean` | Represents a boolean value. |
## PivotGroupValueMetadata
Metadata about a value in a pivot grouping.
| Field | Type | Description |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `collapsed` | `boolean` | True if the data corresponding to the value is collapsed. |
| `value` | [ExtendedValue](#extendedvalue) | The calculated value the metadata corresponds to. (Note that formulaValue is not valid, because the values will be calculated.) |
## PivotGroupRule
An optional setting on a PivotGroup that defines buckets for the values in the source data column rather than breaking out each individual value. Only one PivotGroup with a group rule may be added for each column in the source data, though on any given column you may add both a PivotGroup that has a rule and a PivotGroup that does not.
| Field | Type | Description |
| --------------- | ------------------------------- | ---------------- |
| `manualRule` | [ManualRule](#manualrule) | A ManualRule. |
| `dateTimeRule` | [DateTimeRule](#datetimerule) | A DateTimeRule. |
| `histogramRule` | [HistogramRule](#histogramrule) | A HistogramRule. |
## ManualRule
Allows you to manually organize the values in a source data column into buckets with names of your choosing. For example, a pivot table that aggregates population by state: +-------+-------------------+ | State | SUM of Population | +-------+-------------------+ | AK | 0.7 | | AL | 4.8 | | AR | 2.9 | ... +-------+-------------------+ could be turned into a pivot table that aggregates population by time zone by providing a list of groups (for example, groupName = 'Central', items = \['AL', 'AR', 'IA', ...]) to a manual group rule. Note that a similar effect could be achieved by adding a time zone column to the source data and adjusting the pivot table. +-----------+-------------------+ | Time Zone | SUM of Population | +-----------+-------------------+ | Central | 106.3 | | Eastern | 151.9 | | Mountain | 17.4 | ... +-----------+-------------------+
| Field | Type | Description |
| -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `groups` | [ManualRuleGroup](#manualrulegroup)\[] | The list of group names and the corresponding items from the source data that map to each group name. |
## ManualRuleGroup
A group name and a list of items from the source data that should be placed in the group with this name.
| Field | Type | Description |
| ----------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` | [ExtendedValue](#extendedvalue)\[] | The items in the source data that should be placed into this group. Each item may be a string, number, or boolean. Items may appear in at most one group within a given ManualRule. Items that do not appear in any group will appear on their own. |
| `groupName` | [ExtendedValue](#extendedvalue) | The group name, which must be a string. Each group in a given ManualRule must have a unique group name. |
## DateTimeRule
Allows you to organize the date-time values in a source data column into buckets based on selected parts of their date or time values. For example, consider a pivot table showing sales transactions by date: +----------+--------------+ | Date | SUM of Sales | +----------+--------------+ | 1/1/2017 | $621.14 \| \| 2/3/2017 \| $708.84 | | 5/8/2017 | $326.84 \| ... +----------+--------------+ Applying a date-time group rule with a DateTimeRuleType of YEAR_MONTH results in the following pivot table. +--------------+--------------+ \| Grouped Date \| SUM of Sales \| +--------------+--------------+ \| 2017-Jan \| $53,731.78 | | 2017-Feb | $83,475.32 \| \| 2017-Mar \| $94,385.05 | ... +--------------+--------------+
| Field | Type | Description |
| ------ | ------------------------------------- | ---------------------------------------- |
| `type` | [DateTimeRuleType](#datetimeruletype) | The type of date-time grouping to apply. |
## HistogramRule
Allows you to organize the numeric values in a source data column into buckets of a constant size. All values from HistogramRule.start to HistogramRule.end are placed into groups of size HistogramRule.interval. In addition, all values below HistogramRule.start are placed in one group, and all values above HistogramRule.end are placed in another. Only HistogramRule.interval is required, though if HistogramRule.start and HistogramRule.end are both provided, HistogramRule.start must be less than HistogramRule.end. For example, a pivot table showing average purchase amount by age that has 50+ rows: +-----+-------------------+ | Age | AVERAGE of Amount | +-----+-------------------+ | 16 | $27.13 \| \| 17 \| $5.24 | | 18 | $20.15 \| ... +-----+-------------------+ could be turned into a pivot table that looks like the one below by applying a histogram group rule with a HistogramRule.start of 25, an HistogramRule.interval of 20, and an HistogramRule.end of 65. +-------------+-------------------+ \| Grouped Age \| AVERAGE of Amount \| +-------------+-------------------+ \| < 25 \| $19.34 | | 25-45 | $31.43 \| \| 45-65 \| $35.87 | | > 65 | $27.55 \| +-------------+-------------------+ \| Grand Total \| $29.12 | +-------------+-------------------+
| Field | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `end` | `number` | The maximum value at which items are placed into buckets of constant size. Values above end are lumped into a single bucket. This field is optional. |
| `start` | `number` | The minimum value at which items are placed into buckets of constant size. Values below start are lumped into a single bucket. This field is optional. |
| `interval` | `number` | The size of the buckets that are created. Must be positive. |
## PivotGroupLimit
The count limit on rows or columns in the pivot group.
| Field | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `countLimit` | `integer` | The count limit. |
| `applyOrder` | `integer` | The order in which the group limit is applied to the pivot table. Pivot group limits are applied from lower to higher order number. Order numbers are normalized to consecutive integers from 0. For write request, to fully customize the applying orders, all pivot group limits should have this field set with an unique number. Otherwise, the order is determined by the index in the PivotTable.rows list and then the PivotTable.columns list. |
## TextFormatRun
A run of a text format. The format of this run continues until the start index of the next run. When updating, all fields must be set.
| Field | Type | Description |
| ------------ | ------------------------- | --------------------------------------------------------------------------- |
| `startIndex` | `integer` | The zero-based character index where this run starts, in UTF-16 code units. |
| `format` | [TextFormat](#textformat) | The format of this run. Absent values inherit the cell's format. |
## EmbeddedChart
A chart embedded in a sheet.
| Field | Type | Description |
| ---------- | ------------------------------------------------- | ------------------------------- |
| `spec` | [ChartSpec](#chartspec) | The specification of the chart. |
| `chartId` | `integer` | The ID of the chart. |
| `position` | [EmbeddedObjectPosition](#embeddedobjectposition) | The position of the chart. |
| `border` | [EmbeddedObjectBorder](#embeddedobjectborder) | The border of the chart. |
## ChartSpec
The specifications of a chart.
| Field | Type | Description |
| --------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scorecardChart` | [ScorecardChartSpec](#scorecardchartspec) | A scorecard chart specification. |
| `bubbleChart` | [BubbleChartSpec](#bubblechartspec) | A bubble chart specification. |
| `histogramChart` | [HistogramChartSpec](#histogramchartspec) | A histogram chart specification. |
| `candlestickChart` | [CandlestickChartSpec](#candlestickchartspec) | A candlestick chart specification. |
| `waterfallChart` | [WaterfallChartSpec](#waterfallchartspec) | A waterfall chart specification. |
| `orgChart` | [OrgChartSpec](#orgchartspec) | An org chart specification. |
| `backgroundColorStyle` | [ColorStyle](#colorstyle) | The background color of the entire chart. Not applicable to Org charts. If background\_color is also set, this field takes precedence. |
| `sortSpecs` | [SortSpec](#sortspec)\[] | The order to sort the chart data by. Only a single sort spec is supported. Only supported for data source charts. |
| `title` | `string` | The title of the chart. |
| `pieChart` | [PieChartSpec](#piechartspec) | A pie chart specification. |
| `altText` | `string` | The alternative text that describes the chart. This is often used for accessibility. |
| `titleTextPosition` | [TextPosition](#textposition) | The title text position. This field is optional. |
| `titleTextFormat` | [TextFormat](#textformat) | The title text format. Strikethrough, underline, and link are not supported. |
| `filterSpecs` | [FilterSpec](#filterspec)\[] | The filters applied to the source data of the chart. Only supported for data source charts. |
| `subtitleTextFormat` | [TextFormat](#textformat) | The subtitle text format. Strikethrough, underline, and link are not supported. |
| `subtitle` | `string` | The subtitle of the chart. |
| `subtitleTextPosition` | [TextPosition](#textposition) | The subtitle text position. This field is optional. |
| `fontName` | `string` | The name of the font to use by default for all chart text (e.g. title, axis labels, legend). If a font is specified for a specific part of the chart it will override this font name. |
| `maximized` | `boolean` | True to make a chart fill the entire space in which it's rendered with minimum padding. False to use the default padding. (Not applicable to Geo and Org charts.) |
| `hiddenDimensionStrategy` | [ChartSpecHiddenDimensionStrategy](#chartspechiddendimensionstrategy) | Determines how the charts will use hidden rows or columns. |
| `dataSourceChartProperties` | [DataSourceChartProperties](#datasourcechartproperties) | If present, the field contains data source chart specific properties. |
| `basicChart` | [BasicChartSpec](#basicchartspec) | A basic chart specification, can be one of many kinds of charts. See BasicChartType for the list of all charts this supports. |
| `treemapChart` | [TreemapChartSpec](#treemapchartspec) | A treemap chart specification. |
## ScorecardChartSpec
A scorecard chart. Scorecard charts are used to highlight key performance indicators, known as KPIs, on the spreadsheet. A scorecard chart can represent things like total sales, average cost, or a top selling item. You can specify a single data value, or aggregate over a range of data. Percentage or absolute difference from a baseline value can be highlighted, like changes over time.
| Field | Type | Description |
| --------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aggregateType` | [ScorecardChartSpecAggregateType](#scorecardchartspecaggregatetype) | The aggregation type for key and baseline chart data in scorecard chart. This field is not supported for data source charts. Use the ChartData.aggregateType field of the key\_value\_data or baseline\_value\_data instead for data source charts. This field is optional. |
| `customFormatOptions` | [ChartCustomNumberFormatOptions](#chartcustomnumberformatoptions) | Custom formatting options for numeric key/baseline values in scorecard chart. This field is used only when number\_format\_source is set to CUSTOM. This field is optional. |
| `numberFormatSource` | [ScorecardChartSpecNumberFormatSource](#scorecardchartspecnumberformatsource) | The number format source used in the scorecard chart. This field is optional. |
| `keyValueData` | [ChartData](#chartdata) | The data for scorecard key value. |
| `keyValueFormat` | [KeyValueFormat](#keyvalueformat) | Formatting options for key value. |
| `baselineValueData` | [ChartData](#chartdata) | The data for scorecard baseline value. This field is optional. |
| `baselineValueFormat` | [BaselineValueFormat](#baselinevalueformat) | Formatting options for baseline value. This field is needed only if baseline\_value\_data is specified. |
| `scaleFactor` | `number` | Value to scale scorecard key and baseline value. For example, a factor of 10 can be used to divide all values in the chart by 10. This field is optional. |
## ChartCustomNumberFormatOptions
Custom number formatting options for chart attributes.
| Field | Type | Description |
| -------- | -------- | ----------------------------------------------------------------------------- |
| `prefix` | `string` | Custom prefix to be prepended to the chart attribute. This field is optional. |
| `suffix` | `string` | Custom suffix to be appended to the chart attribute. This field is optional. |
## ChartData
The data included in a domain or series.
| Field | Type | Description |
| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `sourceRange` | [ChartSourceRange](#chartsourcerange) | The source ranges of the data. |
| `columnReference` | [DataSourceColumnReference](#datasourcecolumnreference) | The reference to the data source column that the data reads from. |
| `aggregateType` | [ScorecardChartSpecAggregateType](#scorecardchartspecaggregatetype) | The aggregation type for the series of a data source chart. Only supported for data source charts. |
| `groupRule` | [ChartGroupRule](#chartgrouprule) | The rule to group the data by if the ChartData backs the domain of a data source chart. Only supported for data source charts. |
## ChartSourceRange
Source ranges for a chart.
| Field | Type | Description |
| --------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sources` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange)\[] | The ranges of data for a series or domain. Exactly one dimension must have a length of 1, and all sources in the list must have the same dimension with length 1. The domain (if it exists) & all series must have the same number of source ranges. If using more than one source range, then the source range at a given offset must be in order and contiguous across the domain and series. For example, these are valid configurations: domain sources: A1:A5 series1 sources: B1:B5 series2 sources: D6:D10 domain sources: A1:A5, C10:C12 series1 sources: B1:B5, D10:D12 series2 sources: C1:C5, E10:E12 |
## ChartGroupRule
An optional setting on the ChartData of the domain of a data source chart that defines buckets for the values in the domain rather than breaking out each individual value. For example, when plotting a data source chart, you can specify a histogram rule on the domain (it should only contain numeric values), grouping its values into buckets. Any values of a chart series that fall into the same bucket are aggregated based on the aggregate\_type.
| Field | Type | Description |
| --------------- | ----------------------------------------- | -------------------- |
| `histogramRule` | [ChartHistogramRule](#charthistogramrule) | A ChartHistogramRule |
| `dateTimeRule` | [ChartDateTimeRule](#chartdatetimerule) | A ChartDateTimeRule. |
## ChartHistogramRule
Allows you to organize numeric values in a source data column into buckets of constant size.
| Field | Type | Description |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minValue` | `number` | The minimum value at which items are placed into buckets. Values that are less than the minimum are grouped into a single bucket. If omitted, it is determined by the minimum item value. |
| `intervalSize` | `number` | The size of the buckets that are created. Must be positive. |
| `maxValue` | `number` | The maximum value at which items are placed into buckets. Values greater than the maximum are grouped into a single bucket. If omitted, it is determined by the maximum item value. |
## ChartDateTimeRule
Allows you to organize the date-time values in a source data column into buckets based on selected parts of their date or time values.
| Field | Type | Description |
| ------ | ----------------------------------------------- | ---------------------------------------- |
| `type` | [ChartDateTimeRuleType](#chartdatetimeruletype) | The type of date-time grouping to apply. |
## KeyValueFormat
Formatting options for key value.
| Field | Type | Description |
| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `position` | [TextPosition](#textposition) | Specifies the horizontal text positioning of key value. This field is optional. If not specified, default positioning is used. |
| `textFormat` | [TextFormat](#textformat) | Text formatting options for key value. The link field is not supported. |
## TextPosition
Position settings for text.
| Field | Type | Description |
| --------------------- | ----------------------------------- | --------------------------------------------------- |
| `horizontalAlignment` | [HorizontalAlign](#horizontalalign) | Horizontal alignment setting for the piece of text. |
## BaselineValueFormat
Formatting options for baseline value.
| Field | Type | Description |
| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | `string` | Description which is appended after the baseline value. This field is optional. |
| `textFormat` | [TextFormat](#textformat) | Text formatting options for baseline value. The link field is not supported. |
| `position` | [TextPosition](#textposition) | Specifies the horizontal text positioning of baseline value. This field is optional. If not specified, default positioning is used. |
| `comparisonType` | [BaselineValueFormatComparisonType](#baselinevalueformatcomparisontype) | The comparison type of key value with baseline value. |
| `negativeColorStyle` | [ColorStyle](#colorstyle) | Color to be used, in case baseline value represents a negative change for key value. This field is optional. If negative\_color is also set, this field takes precedence. |
| `positiveColorStyle` | [ColorStyle](#colorstyle) | Color to be used, in case baseline value represents a positive change for key value. This field is optional. If positive\_color is also set, this field takes precedence. |
## BubbleChartSpec
A bubble chart.
| Field | Type | Description |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `groupIds` | [ChartData](#chartdata) | The data containing the bubble group IDs. All bubbles with the same group ID are drawn in the same color. If bubble\_sizes is specified then this field must also be specified but may contain blank values. This field is optional. |
| `bubbleBorderColorStyle` | [ColorStyle](#colorstyle) | The bubble border color. If bubble\_border\_color is also set, this field takes precedence. |
| `bubbleLabels` | [ChartData](#chartdata) | The data containing the bubble labels. These do not need to be unique. |
| `domain` | [ChartData](#chartdata) | The data containing the bubble x-values. These values locate the bubbles in the chart horizontally. |
| `bubbleMaxRadiusSize` | `integer` | The max radius size of the bubbles, in pixels. If specified, the field must be a positive value. |
| `series` | [ChartData](#chartdata) | The data containing the bubble y-values. These values locate the bubbles in the chart vertically. |
| `bubbleOpacity` | `number` | The opacity of the bubbles between 0 and 1.0. 0 is fully transparent and 1 is fully opaque. |
| `bubbleTextStyle` | [TextFormat](#textformat) | The format of the text inside the bubbles. Strikethrough, underline, and link are not supported. |
| `legendPosition` | [BubbleChartSpecLegendPosition](#bubblechartspeclegendposition) | Where the legend of the chart should be drawn. |
| `bubbleMinRadiusSize` | `integer` | The minimum radius size of the bubbles, in pixels. If specific, the field must be a positive value. |
| `bubbleSizes` | [ChartData](#chartdata) | The data containing the bubble sizes. Bubble sizes are used to draw the bubbles at different sizes relative to each other. If specified, group\_ids must also be specified. This field is optional. |
## HistogramChartSpec
A histogram chart. A histogram chart groups data items into bins, displaying each bin as a column of stacked items. Histograms are used to display the distribution of a dataset. Each column of items represents a range into which those items fall. The number of bins can be chosen automatically or specified explicitly.
| Field | Type | Description |
| ------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outlierPercentile` | `number` | The outlier percentile is used to ensure that outliers do not adversely affect the calculation of bucket sizes. For example, setting an outlier percentile of 0.05 indicates that the top and bottom 5% of values when calculating buckets. The values are still included in the chart, they will be added to the first or last buckets instead of their own buckets. Must be between 0.0 and 0.5. ≥ 0.0; ≤ 0.5 |
| `series` | [HistogramSeries](#histogramseries)\[] | The series for a histogram may be either a single series of values to be bucketed or multiple series, each of the same length, containing the name of the series followed by the values to be bucketed for that series. |
| `bucketSize` | `number` | By default the bucket size (the range of values stacked in a single column) is chosen automatically, but it may be overridden here. E.g., A bucket size of 1.5 results in buckets from 0 - 1.5, 1.5 - 3.0, etc. Cannot be negative. This field is optional. |
| `showItemDividers` | `boolean` | Whether horizontal divider lines should be displayed between items in each column. |
| `legendPosition` | [HistogramChartSpecLegendPosition](#histogramchartspeclegendposition) | The position of the chart legend. |
## HistogramSeries
A histogram series containing the series color and data.
| Field | Type | Description |
| --------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `barColorStyle` | [ColorStyle](#colorstyle) | The color of the column representing this series in each bucket. This field is optional. If bar\_color is also set, this field takes precedence. |
| `data` | [ChartData](#chartdata) | The data for this histogram series. |
## CandlestickChartSpec
A candlestick chart.
| Field | Type | Description |
| -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | [CandlestickData](#candlestickdata)\[] | The Candlestick chart data. Only one CandlestickData is supported. |
| `domain` | [CandlestickDomain](#candlestickdomain) | The domain data (horizontal axis) for the candlestick chart. String data will be treated as discrete labels, other data will be treated as continuous values. |
## CandlestickData
The Candlestick chart data, each containing the low, open, close, and high values for a series.
| Field | Type | Description |
| ------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `highSeries` | [CandlestickSeries](#candlestickseries) | The range data (vertical axis) for the high/maximum value for each candle. This is the top of the candle's center line. |
| `closeSeries` | [CandlestickSeries](#candlestickseries) | The range data (vertical axis) for the close/final value for each candle. This is the top of the candle body. If greater than the open value the candle will be filled. Otherwise the candle will be hollow. |
| `lowSeries` | [CandlestickSeries](#candlestickseries) | The range data (vertical axis) for the low/minimum value for each candle. This is the bottom of the candle's center line. |
| `openSeries` | [CandlestickSeries](#candlestickseries) | The range data (vertical axis) for the open/initial value for each candle. This is the bottom of the candle body. If less than the close value the candle will be filled. Otherwise the candle will be hollow. |
## CandlestickSeries
The series of a CandlestickData.
| Field | Type | Description |
| ------ | ----------------------- | ---------------------------------- |
| `data` | [ChartData](#chartdata) | The data of the CandlestickSeries. |
## CandlestickDomain
The domain of a CandlestickChart.
| Field | Type | Description |
| ---------- | ----------------------- | ----------------------------------------------------------------- |
| `reversed` | `boolean` | True to reverse the order of the domain values (horizontal axis). |
| `data` | [ChartData](#chartdata) | The data of the CandlestickDomain. |
## WaterfallChartSpec
A waterfall chart.
| Field | Type | Description |
| -------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectorLineStyle` | [LineStyle](#linestyle) | The line style for the connector lines. |
| `totalDataLabel` | [DataLabel](#datalabel) | Controls whether to display additional data labels on stacked charts which sum the total value of all stacked values at each value along the domain axis. stacked\_type must be STACKED and neither CUSTOM nor placement can be set on the total\_data\_label. |
| `series` | [WaterfallChartSeries](#waterfallchartseries)\[] | The data this waterfall chart is visualizing. |
| `stackedType` | [WaterfallChartSpecStackedType](#waterfallchartspecstackedtype) | The stacked type. |
| `domain` | [WaterfallChartDomain](#waterfallchartdomain) | The domain data (horizontal axis) for the waterfall chart. |
| `firstValueIsTotal` | `boolean` | True to interpret the first value as a total. |
| `hideConnectorLines` | `boolean` | True to hide connector lines between columns. |
## LineStyle
Properties that describe the style of a line.
| Field | Type | Description |
| ------- | ------------------------------- | --------------------------------- |
| `type` | [LineStyleType](#linestyletype) | The dash type of the line. |
| `width` | `integer` | The thickness of the line, in px. |
## DataLabel
Settings for one set of data labels. Data labels are annotations that appear next to a set of data, such as the points on a line chart, and provide additional information about what the data represents, such as a text representation of the value behind that point on the graph.
| Field | Type | Description |
| ----------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customLabelData` | [ChartData](#chartdata) | Data to use for custom labels. Only used if type is set to CUSTOM. This data must be the same length as the series or other element this data label is applied to. In addition, if the series is split into multiple source ranges, this source data must come from the next column in the source data. For example, if the series is B2:B4,E6:E8 then this data must come from C2:C4,F6:F8. |
| `textFormat` | [TextFormat](#textformat) | The text format used for the data label. The link field is not supported. |
| `type` | [DataLabelType](#datalabeltype) | The type of the data label. |
| `placement` | [DataLabelPlacement](#datalabelplacement) | The placement of the data label relative to the labeled data. |
## WaterfallChartSeries
A single series of data for a waterfall chart.
| Field | Type | Description |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `negativeColumnsStyle` | [WaterfallChartColumnStyle](#waterfallchartcolumnstyle) | Styles for all columns in this series with negative values. |
| `subtotalColumnsStyle` | [WaterfallChartColumnStyle](#waterfallchartcolumnstyle) | Styles for all subtotal columns in this series. |
| `hideTrailingSubtotal` | `boolean` | True to hide the subtotal column from the end of the series. By default, a subtotal column will appear at the end of each series. Setting this field to true will hide that subtotal column for this series. |
| `dataLabel` | [DataLabel](#datalabel) | Information about the data labels for this series. |
| `data` | [ChartData](#chartdata) | The data being visualized in this series. |
| `customSubtotals` | [WaterfallChartCustomSubtotal](#waterfallchartcustomsubtotal)\[] | Custom subtotal columns appearing in this series. The order in which subtotals are defined is not significant. Only one subtotal may be defined for each data point. |
| `positiveColumnsStyle` | [WaterfallChartColumnStyle](#waterfallchartcolumnstyle) | Styles for all columns in this series with positive values. |
## WaterfallChartColumnStyle
Styles for a waterfall chart column.
| Field | Type | Description |
| ------------ | ------------------------- | --------------------------------------------------------------------------- |
| `label` | `string` | The label of the column's legend. |
| `colorStyle` | [ColorStyle](#colorstyle) | The color of the column. If color is also set, this field takes precedence. |
## WaterfallChartCustomSubtotal
A custom subtotal column for a waterfall chart series.
| Field | Type | Description |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subtotalIndex` | `integer` | The zero-based index of a data point within the series. If data\_is\_subtotal is true, the data point at this index is the subtotal. Otherwise, the subtotal appears after the data point with this index. A series can have multiple subtotals at arbitrary indices, but subtotals do not affect the indices of the data points. For example, if a series has three data points, their indices will always be 0, 1, and 2, regardless of how many subtotals exist on the series or what data points they are associated with. |
| `label` | `string` | A label for the subtotal column. |
| `dataIsSubtotal` | `boolean` | True if the data point at subtotal\_index is the subtotal. If false, the subtotal will be computed and appear after the data point. |
## WaterfallChartDomain
The domain of a waterfall chart.
| Field | Type | Description |
| ---------- | ----------------------- | ----------------------------------------------------------------- |
| `reversed` | `boolean` | True to reverse the order of the domain values (horizontal axis). |
| `data` | [ChartData](#chartdata) | The data of the WaterfallChartDomain. |
## OrgChartSpec
An org chart. Org charts require a unique set of labels in labels and may optionally include parent\_labels and tooltips. parent\_labels contain, for each node, the label identifying the parent node. tooltips contain, for each node, an optional tooltip. For example, to describe an OrgChart with Alice as the CEO, Bob as the President (reporting to Alice) and Cathy as VP of Sales (also reporting to Alice), have labels contain "Alice", "Bob", "Cathy", parent\_labels contain "", "Alice", "Alice" and tooltips contain "CEO", "President", "VP Sales".
| Field | Type | Description |
| ------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parentLabels` | [ChartData](#chartdata) | The data containing the label of the parent for the corresponding node. A blank value indicates that the node has no parent and is a top-level node. This field is optional. |
| `nodeColorStyle` | [ColorStyle](#colorstyle) | The color of the org chart nodes. If node\_color is also set, this field takes precedence. |
| `nodeSize` | [OrgChartSpecNodeSize](#orgchartspecnodesize) | The size of the org chart nodes. |
| `tooltips` | [ChartData](#chartdata) | The data containing the tooltip for the corresponding node. A blank value results in no tooltip being displayed for the node. This field is optional. |
| `labels` | [ChartData](#chartdata) | The data containing the labels for all the nodes in the chart. Labels must be unique. |
| `selectedNodeColorStyle` | [ColorStyle](#colorstyle) | The color of the selected org chart nodes. If selected\_node\_color is also set, this field takes precedence. |
## PieChartSpec
A pie chart.
| Field | Type | Description |
| ------------------ | --------------------------------------------------------- | -------------------------------------------------------------- |
| `domain` | [ChartData](#chartdata) | The data that covers the domain of the pie chart. |
| `legendPosition` | [PieChartSpecLegendPosition](#piechartspeclegendposition) | Where the legend of the pie chart should be drawn. |
| `series` | [ChartData](#chartdata) | The data that covers the one and only series of the pie chart. |
| `pieHole` | `number` | The size of the hole in the pie chart. |
| `threeDimensional` | `boolean` | True if the pie is three dimensional. |
## DataSourceChartProperties
Properties of a data source chart.
| Field | Type | Description |
| -------------- | -------- | -------------------------------------------------------- |
| `dataSourceId` | `string` | ID of the data source that the chart is associated with. |
## BasicChartSpec
The specification for a basic chart. See BasicChartType for the list of charts this supports.
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legendPosition` | [BasicChartSpecLegendPosition](#basicchartspeclegendposition) | The position of the chart legend. |
| `chartType` | [BasicChartSeriesType](#basicchartseriestype) | The type of the chart. |
| `stackedType` | [BasicChartSpecStackedType](#basicchartspecstackedtype) | The stacked type for charts that support vertical stacking. Applies to Area, Bar, Column, Combo, and Stepped Area charts. |
| `series` | [BasicChartSeries](#basicchartseries)\[] | The data this chart is visualizing. |
| `compareMode` | [BasicChartSpecCompareMode](#basicchartspeccomparemode) | The behavior of tooltips and data highlighting when hovering on data and chart area. |
| `domains` | [BasicChartDomain](#basicchartdomain)\[] | The domain of data this is charting. Only a single domain is supported. |
| `threeDimensional` | `boolean` | True to make the chart 3D. Applies to Bar and Column charts. |
| `interpolateNulls` | `boolean` | If some values in a series are missing, gaps may appear in the chart (e.g, segments of lines in a line chart will be missing). To eliminate these gaps set this to true. Applies to Line, Area, and Combo charts. |
| `lineSmoothing` | `boolean` | Gets whether all lines should be rendered smooth or straight by default. Applies to Line charts. |
| `headerCount` | `integer` | The number of rows or columns in the data that are "headers". If not set, Google Sheets will guess how many rows are headers based on the data. (Note that BasicChartAxis.title may override the axis title inferred from the header values.) |
| `totalDataLabel` | [DataLabel](#datalabel) | Controls whether to display additional data labels on stacked charts which sum the total value of all stacked values at each value along the domain axis. These data labels can only be set when chart\_type is one of AREA, BAR, COLUMN, COMBO or STEPPED\_AREA and stacked\_type is either STACKED or PERCENT\_STACKED. In addition, for COMBO, this will only be supported if there is only one type of stackable series type or one type has more series than the others and each of the other types have no more than one series. For example, if a chart has two stacked bar series and one area series, the total data labels will be supported. If it has three bar series and two area series, total data labels are not allowed. Neither CUSTOM nor placement can be set on the total\_data\_label. |
| `axis` | [BasicChartAxis](#basicchartaxis)\[] | The axis on the chart. |
## BasicChartSeries
A single series of data in a chart. For example, if charting stock prices over time, multiple series may exist, one for the "Open Price", "High Price", "Low Price" and "Close Price".
| Field | Type | Description |
| ---------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `series` | [ChartData](#chartdata) | The data being visualized in this chart series. |
| `dataLabel` | [DataLabel](#datalabel) | Information about the data labels for this series. |
| `pointStyle` | [PointStyle](#pointstyle) | The style for points associated with this series. Valid only if the chartType is AREA, LINE, or SCATTER. COMBO charts are also supported if the series chart type is AREA, LINE, or SCATTER. If empty, a default point style is used. |
| `type` | [BasicChartSeriesType](#basicchartseriestype) | The type of this series. Valid only if the chartType is COMBO. Different types will change the way the series is visualized. Only LINE, AREA, and COLUMN are supported. |
| `targetAxis` | [BasicChartSeriesTargetAxis](#basicchartseriestargetaxis) | The minor axis that will specify the range of values for this series. For example, if charting stocks over time, the "Volume" series may want to be pinned to the right with the prices pinned to the left, because the scale of trading volume is different than the scale of prices. It is an error to specify an axis that isn't a valid minor axis for the chart's type. |
| `styleOverrides` | [BasicSeriesDataPointStyleOverride](#basicseriesdatapointstyleoverride)\[] | Style override settings for series data points. |
| `lineStyle` | [LineStyle](#linestyle) | The line style of this series. Valid only if the chartType is AREA, LINE, or SCATTER. COMBO charts are also supported if the series chart type is AREA or LINE. |
| `colorStyle` | [ColorStyle](#colorstyle) | The color for elements (such as bars, lines, and points) associated with this series. If empty, a default color is used. If color is also set, this field takes precedence. |
## PointStyle
The style of a point on the chart.
| Field | Type | Description |
| ------- | ----------------------------------- | ------------------------------------------------------------------ |
| `shape` | [PointStyleShape](#pointstyleshape) | The point shape. If empty or unspecified, a default shape is used. |
| `size` | `number` | The point size. If empty, a default size is used. |
## BasicSeriesDataPointStyleOverride
Style override settings for a single series data point.
| Field | Type | Description |
| ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `colorStyle` | [ColorStyle](#colorstyle) | Color of the series data point. If empty, the series default is used. If color is also set, this field takes precedence. |
| `pointStyle` | [PointStyle](#pointstyle) | Point style of the series data point. Valid only if the chartType is AREA, LINE, or SCATTER. COMBO charts are also supported if the series chart type is AREA, LINE, or SCATTER. If empty, the series default is used. |
| `index` | `integer` | The zero-based index of the series data point. |
## BasicChartDomain
The domain of a chart. For example, if charting stock prices over time, this would be the date.
| Field | Type | Description |
| ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `domain` | [ChartData](#chartdata) | The data of the domain. For example, if charting stock prices over time, this is the data representing the dates. |
| `reversed` | `boolean` | True to reverse the order of the domain values (horizontal axis). |
## BasicChartAxis
An axis of the chart. A chart may not have more than one axis per axis position.
| Field | Type | Description |
| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `title` | `string` | The title of this axis. If set, this overrides any title inferred from headers of the data. |
| `format` | [TextFormat](#textformat) | The format of the title. Only valid if the axis is not associated with the domain. The link field is not supported. |
| `viewWindowOptions` | [ChartAxisViewWindowOptions](#chartaxisviewwindowoptions) | The view window options for this axis. |
| `titleTextPosition` | [TextPosition](#textposition) | The axis title text position. |
| `position` | [BasicChartSeriesTargetAxis](#basicchartseriestargetaxis) | The position of this axis. |
## ChartAxisViewWindowOptions
The options that define a "view window" for a chart (such as the visible values in an axis).
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `viewWindowMin` | `number` | The minimum numeric value to be shown in this view window. If unset, will automatically determine a minimum value that looks good for the data. |
| `viewWindowMax` | `number` | The maximum numeric value to be shown in this view window. If unset, will automatically determine a maximum value that looks good for the data. |
| `viewWindowMode` | [ChartAxisViewWindowOptionsViewWindowMode](#chartaxisviewwindowoptionsviewwindowmode) | The view window's mode. |
## TreemapChartSpec
A Treemap chart.
| Field | Type | Description |
| ------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sizeData` | [ChartData](#chartdata) | The data that determines the size of each treemap data cell. This data is expected to be numeric. The cells corresponding to non-numeric or missing data will not be rendered. If color\_data is not specified, this data is used to determine data cell background colors as well. |
| `parentLabels` | [ChartData](#chartdata) | The data the contains the treemap cells' parent labels. |
| `minValue` | `number` | The minimum possible data value. Cells with values less than this will have the same color as cells with this value. If not specified, defaults to the actual minimum value from color\_data, or the minimum value from size\_data if color\_data is not specified. |
| `colorData` | [ChartData](#chartdata) | The data that determines the background color of each treemap data cell. This field is optional. If not specified, size\_data is used to determine background colors. If specified, the data is expected to be numeric. color\_scale will determine how the values in this data map to data cell background colors. |
| `hideTooltips` | `boolean` | True to hide tooltips. |
| `textFormat` | [TextFormat](#textformat) | The text format for all labels on the chart. The link field is not supported. |
| `headerColorStyle` | [ColorStyle](#colorstyle) | The background color for header cells. If header\_color is also set, this field takes precedence. |
| `colorScale` | [TreemapChartColorScale](#treemapchartcolorscale) | The color scale for data cells in the treemap chart. Data cells are assigned colors based on their color values. These color values come from color\_data, or from size\_data if color\_data is not specified. Cells with color values less than or equal to min\_value will have minValueColor as their background color. Cells with color values greater than or equal to max\_value will have maxValueColor as their background color. Cells with color values between min\_value and max\_value will have background colors on a gradient between minValueColor and maxValueColor, the midpoint of the gradient being midValueColor. Cells with missing or non-numeric color values will have noDataColor as their background color. |
| `levels` | `integer` | The number of data levels to show on the treemap chart. These levels are interactive and are shown with their labels. Defaults to 2 if not specified. |
| `maxValue` | `number` | The maximum possible data value. Cells with values greater than this will have the same color as cells with this value. If not specified, defaults to the actual maximum value from color\_data, or the maximum value from size\_data if color\_data is not specified. |
| `labels` | [ChartData](#chartdata) | The data that contains the treemap cell labels. |
| `hintedLevels` | `integer` | The number of additional data levels beyond the labeled levels to be shown on the treemap chart. These levels are not interactive and are shown without their labels. Defaults to 0 if not specified. |
## TreemapChartColorScale
A color scale for a treemap chart.
| Field | Type | Description |
| -------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minValueColorStyle` | [ColorStyle](#colorstyle) | The background color for cells with a color value less than or equal to minValue. Defaults to #dc3912 if not specified. If min\_value\_color is also set, this field takes precedence. |
| `maxValueColorStyle` | [ColorStyle](#colorstyle) | The background color for cells with a color value greater than or equal to maxValue. Defaults to #109618 if not specified. If max\_value\_color is also set, this field takes precedence. |
| `midValueColorStyle` | [ColorStyle](#colorstyle) | The background color for cells with a color value at the midpoint between minValue and maxValue. Defaults to #efe6dc if not specified. If mid\_value\_color is also set, this field takes precedence. |
| `noDataColorStyle` | [ColorStyle](#colorstyle) | The background color for cells that have no color data associated with them. Defaults to #000000 if not specified. If no\_data\_color is also set, this field takes precedence. |
## EmbeddedObjectBorder
A border along an embedded object.
| Field | Type | Description |
| ------------ | ------------------------- | --------------------------------------------------------------------------- |
| `colorStyle` | [ColorStyle](#colorstyle) | The color of the border. If color is also set, this field takes precedence. |
## FilterView
A filter view. For more information, see [Manage data visibility with filters](https://developers.google.com/workspace/sheets/api/guides/filters).
| Field | Type | Description |
| -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableId` | `string` | The table this filter view is backed by, if any. When writing, only one of range, named\_range\_id, or table\_id may be set. |
| `namedRangeId` | `string` | The named range this filter view is backed by, if any. When writing, only one of range, named\_range\_id, or table\_id may be set. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range this filter view covers. When writing, only one of range, named\_range\_id, or table\_id may be set. |
| `sortSpecs` | [SortSpec](#sortspec)\[] | The sort order per column. Later specifications are used when values are equal in the earlier specifications. |
| `title` | `string` | The name of the filter view. |
| `filterViewId` | `integer` | The ID of the filter view. |
| `filterSpecs` | [FilterSpec](#filterspec)\[] | The filter criteria for showing or hiding values per column. Both criteria and filter\_specs are populated in responses. If both fields are specified in an update request, this field takes precedence. |
## ProtectedRange
A protected range.
| Field | Type | Description |
| ------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namedRangeId` | `string` | The named range this protected range is backed by, if any. When writing, only one of range or named\_range\_id or table\_id may be set. |
| `unprotectedRanges` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange)\[] | The list of unprotected ranges within a protected sheet. Unprotected ranges are only supported on protected sheets. |
| `description` | `string` | The description of this protected range. |
| `warningOnly` | `boolean` | True if this protected range will show a warning when editing. Warning-based protection means that every user can edit data in the protected range, except editing will prompt a warning asking the user to confirm the edit. When writing: if this field is true, then editors are ignored. Additionally, if this field is changed from true to false and the `editors` field is not set (nor included in the field mask), then the editors will be set to all the editors in the document. |
| `editors` | [Editors](#editors) | The users and groups with edit access to the protected range. This field is only visible to users with edit access to the protected range and the document. Editors are not supported with warning\_only protection. |
| `tableId` | `string` | The table this protected range is backed by, if any. When writing, only one of range or named\_range\_id or table\_id may be set. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range that is being protected. The range may be fully unbounded, in which case this is considered a protected sheet. When writing, only one of range or named\_range\_id or table\_id may be set. |
## Editors
The editors of a protected range.
| Field | Type | Description |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domainUsersCanEdit` | `boolean` | True if anyone in the document's domain has edit access to the protected range. Domain protection is only supported on documents within a domain. |
| `users` | `string`\[] | The email addresses of users with edit access to the protected range. |
| `groups` | `string`\[] | The email addresses of groups with edit access to the protected range. |
## CommentAnchor
A location in the spreadsheet that is tied to a CommentThread with the same anchorId. Note: Multiple anchors may refer to the same location.
| Field | Type | Description |
| ------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The coordinate range inside the sheet where this comment is anchored. |
## DataSource
Information about an external data source in the spreadsheet.
| Field | Type | Description |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec` | [DataSourceSpec](#datasourcespec) | The DataSourceSpec for the data source connected with this spreadsheet. |
| `dataSourceId` | `string` | The spreadsheet-scoped unique ID that identifies the data source. Example: 1080547365. |
| `calculatedColumns` | [DataSourceColumn](#datasourcecolumn)\[] | All calculated columns in the data source. |
| `sheetId` | `integer` | The ID of the Sheet connected with the data source. The field cannot be changed once set. When creating a data source, an associated DATA\_SOURCE sheet is also created, if the field is not specified, the ID of the created sheet will be randomly generated. |
## DataSourceSpec
This specifies the details of the data source. For example, for BigQuery, this specifies information about the BigQuery source.
| Field | Type | Description |
| ------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `bigQuery` | [BigQueryDataSourceSpec](#bigquerydatasourcespec) | A BigQueryDataSourceSpec. |
| `looker` | [LookerDataSourceSpec](#lookerdatasourcespec) | A LookerDatasourceSpec. |
| `parameters` | [DataSourceParameter](#datasourceparameter)\[] | The parameters of the data source, used when querying the data source. |
## BigQueryDataSourceSpec
The specification of a BigQuery data source that's connected to a sheet.
| Field | Type | Description |
| ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `querySpec` | [BigQueryQuerySpec](#bigqueryqueryspec) | A BigQueryQuerySpec. |
| `projectId` | `string` | The ID of a BigQuery enabled Google Cloud project with a billing account attached. For any queries executed against the data source, the project is charged. |
| `tableSpec` | [BigQueryTableSpec](#bigquerytablespec) | A BigQueryTableSpec. |
## BigQueryQuerySpec
Specifies a custom BigQuery query.
| Field | Type | Description |
| ---------- | -------- | --------------------- |
| `rawQuery` | `string` | The raw query string. |
## BigQueryTableSpec
Specifies a BigQuery table definition. Only [native tables](https://cloud.google.com/bigquery/docs/tables-intro) are allowed.
| Field | Type | Description |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `datasetId` | `string` | The BigQuery dataset id. |
| `tableProjectId` | `string` | The ID of a BigQuery project the table belongs to. If not specified, the project\_id is assumed. |
| `tableId` | `string` | The BigQuery table id. |
## LookerDataSourceSpec
The specification of a Looker data source.
| Field | Type | Description |
| ------------- | -------- | ------------------------------- |
| `model` | `string` | Name of a Looker model. |
| `explore` | `string` | Name of a Looker model explore. |
| `instanceUri` | `string` | A Looker instance URL. |
## DataSourceParameter
A parameter in a data source's query. The parameter allows the user to pass in values from the spreadsheet into a query.
| Field | Type | Description |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | A range that contains the value of the parameter. Its size must be 1x1. |
| `name` | `string` | Named parameter. Must be a legitimate identifier for the DataSource that supports it. For example, [BigQuery identifier](https://cloud.google.com/bigquery/docs/reference/standard-sql/lexical#identifiers). |
| `namedRangeId` | `string` | ID of a NamedRange. Its size must be 1x1. |
## NamedRange
A named range.
| Field | Type | Description |
| -------------- | ------------------------------------------------------------ | ---------------------------- |
| `name` | `string` | The name of the named range. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range this represents. |
| `namedRangeId` | `string` | The ID of the named range. |
## CommentThread
Represents a single comment thread inside a spreadsheet.
| Field | Type | Description |
| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| `commentId` | `string` | The unique ID of the comment thread. |
| `anchorId` | `string` | The ID of the comment anchor. |
| `headPost` | [Post](#post) | The first post in the comment thread. |
| `replies` | [Post](#post)\[] | The reply posts in the comment thread. |
| `status` | [CommentThreadStatus](#commentthreadstatus) | The status of the comment thread. |
| `plainTextQuote` | `string` | The quoted spreadsheet content the comment is anchored to, as plain text. |
## Post
A post on a comment thread: the head post or a reply.
| Field | Type | Description |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `content` | `string` | The content of the post. Required to be non-empty if commentAction is not RESOLVE or REOPEN. This text content will be handled similarly to comments created in the Sheets editor. It will have similar behaviors for formatting, notifications, etc. May not exceed 2048 UTF-8 code units. max length 2048 |
| `assigneeEmail` | `string` | Optional. The email of the user who is being newly assigned to the thread as part of this post. Returns a 400 bad request error if: the parent thread is a CommentThread whose headPost does not have an assignee; commentAction is specified as RESOLVE or REOPEN; or assigneeEmail exceeds 2048 UTF-8 code units. max length 2048 |
| `commentAction` | [CommentActionType](#commentactiontype) | Action taken as part of creating the post. |
## Request
A single kind of update to apply to a spreadsheet.
| Field | Type | Description |
| ------------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `updateSpreadsheetProperties` | [UpdateSpreadsheetPropertiesRequest](#updatespreadsheetpropertiesrequest) | Updates the spreadsheet's properties. |
| `updateSheetProperties` | [UpdateSheetPropertiesRequest](#updatesheetpropertiesrequest) | Updates a sheet's properties. |
| `updateDimensionProperties` | [UpdateDimensionPropertiesRequest](#updatedimensionpropertiesrequest) | Updates dimensions' properties. |
| `updateNamedRange` | [UpdateNamedRangeRequest](#updatenamedrangerequest) | Updates a named range. |
| `repeatCell` | [RepeatCellRequest](#repeatcellrequest) | Repeats a single cell across a range. |
| `addNamedRange` | [AddNamedRangeRequest](#addnamedrangerequest) | Adds a named range. |
| `deleteNamedRange` | [DeleteNamedRangeRequest](#deletenamedrangerequest) | Deletes a named range. |
| `addSheet` | [AddSheetRequest](#addsheetrequest) | Adds a sheet. |
| `deleteSheet` | [DeleteSheetRequest](#deletesheetrequest) | Deletes a sheet. |
| `autoFill` | [AutoFillRequest](#autofillrequest) | Automatically fills in more data based on existing data. |
| `cutPaste` | [CutPasteRequest](#cutpasterequest) | Cuts data from one area and pastes it to another. |
| `copyPaste` | [CopyPasteRequest](#copypasterequest) | Copies data from one area and pastes it to another. |
| `mergeCells` | [MergeCellsRequest](#mergecellsrequest) | Merges cells together. |
| `unmergeCells` | [UnmergeCellsRequest](#unmergecellsrequest) | Unmerges merged cells. |
| `updateBorders` | [UpdateBordersRequest](#updatebordersrequest) | Updates the borders in a range of cells. |
| `updateCells` | [UpdateCellsRequest](#updatecellsrequest) | Updates many cells at once. |
| `addFilterView` | [AddFilterViewRequest](#addfilterviewrequest) | Adds a filter view. |
| `appendCells` | [AppendCellsRequest](#appendcellsrequest) | Appends cells after the last row with data in a sheet. |
| `clearBasicFilter` | [ClearBasicFilterRequest](#clearbasicfilterrequest) | Clears the basic filter on a sheet. |
| `deleteDimension` | [DeleteDimensionRequest](#deletedimensionrequest) | Deletes rows or columns in a sheet. |
| `deleteEmbeddedObject` | [DeleteEmbeddedObjectRequest](#deleteembeddedobjectrequest) | Deletes an embedded object (e.g, chart, image) in a sheet. |
| `deleteFilterView` | [DeleteFilterViewRequest](#deletefilterviewrequest) | Deletes a filter view from a sheet. |
| `duplicateFilterView` | [DuplicateFilterViewRequest](#duplicatefilterviewrequest) | Duplicates a filter view. |
| `duplicateSheet` | [DuplicateSheetRequest](#duplicatesheetrequest) | Duplicates a sheet. |
| `findReplace` | [FindReplaceRequest](#findreplacerequest) | Finds and replaces occurrences of some text with other text. |
| `insertDimension` | [InsertDimensionRequest](#insertdimensionrequest) | Inserts new rows or columns in a sheet. |
| `insertRange` | [InsertRangeRequest](#insertrangerequest) | Inserts new cells in a sheet, shifting the existing cells. |
| `moveDimension` | [MoveDimensionRequest](#movedimensionrequest) | Moves rows or columns to another location in a sheet. |
| `updateEmbeddedObjectPosition` | [UpdateEmbeddedObjectPositionRequest](#updateembeddedobjectpositionrequest) | Updates an embedded object's (e.g. chart, image) position. |
| `pasteData` | [PasteDataRequest](#pastedatarequest) | Pastes data (HTML or delimited) into a sheet. |
| `textToColumns` | [TextToColumnsRequest](#texttocolumnsrequest) | Converts a column of text into many columns of text. |
| `updateFilterView` | [UpdateFilterViewRequest](#updatefilterviewrequest) | Updates the properties of a filter view. |
| `deleteRange` | [DeleteRangeRequest](#deleterangerequest) | Deletes a range of cells from a sheet, shifting the remaining cells. |
| `appendDimension` | [AppendDimensionRequest](#appenddimensionrequest) | Appends dimensions to the end of a sheet. |
| `addConditionalFormatRule` | [AddConditionalFormatRuleRequest](#addconditionalformatrulerequest) | Adds a new conditional format rule. |
| `updateConditionalFormatRule` | [UpdateConditionalFormatRuleRequest](#updateconditionalformatrulerequest) | Updates an existing conditional format rule. |
| `deleteConditionalFormatRule` | [DeleteConditionalFormatRuleRequest](#deleteconditionalformatrulerequest) | Deletes an existing conditional format rule. |
| `sortRange` | [SortRangeRequest](#sortrangerequest) | Sorts data in a range. |
| `setDataValidation` | [SetDataValidationRequest](#setdatavalidationrequest) | Sets data validation for one or more cells. |
| `setBasicFilter` | [SetBasicFilterRequest](#setbasicfilterrequest) | Sets the basic filter on a sheet. |
| `addProtectedRange` | [AddProtectedRangeRequest](#addprotectedrangerequest) | Adds a protected range. |
| `updateProtectedRange` | [UpdateProtectedRangeRequest](#updateprotectedrangerequest) | Updates a protected range. |
| `deleteProtectedRange` | [DeleteProtectedRangeRequest](#deleteprotectedrangerequest) | Deletes a protected range. |
| `autoResizeDimensions` | [AutoResizeDimensionsRequest](#autoresizedimensionsrequest) | Automatically resizes one or more dimensions based on the contents of the cells in that dimension. |
| `addChart` | [AddChartRequest](#addchartrequest) | Adds a chart. |
| `updateChartSpec` | [UpdateChartSpecRequest](#updatechartspecrequest) | Updates a chart's specifications. |
| `updateBanding` | [UpdateBandingRequest](#updatebandingrequest) | Updates a banded range |
| `addBanding` | [AddBandingRequest](#addbandingrequest) | Adds a new banded range |
| `deleteBanding` | [DeleteBandingRequest](#deletebandingrequest) | Removes a banded range |
| `createDeveloperMetadata` | [CreateDeveloperMetadataRequest](#createdevelopermetadatarequest) | Creates new developer metadata |
| `updateDeveloperMetadata` | [UpdateDeveloperMetadataRequest](#updatedevelopermetadatarequest) | Updates an existing developer metadata entry |
| `deleteDeveloperMetadata` | [DeleteDeveloperMetadataRequest](#deletedevelopermetadatarequest) | Deletes developer metadata |
| `randomizeRange` | [RandomizeRangeRequest](#randomizerangerequest) | Randomizes the order of the rows in a range. |
| `addDimensionGroup` | [AddDimensionGroupRequest](#adddimensiongrouprequest) | Creates a group over the specified range. |
| `deleteDimensionGroup` | [DeleteDimensionGroupRequest](#deletedimensiongrouprequest) | Deletes a group over the specified range. |
| `updateDimensionGroup` | [UpdateDimensionGroupRequest](#updatedimensiongrouprequest) | Updates the state of the specified group. |
| `trimWhitespace` | [TrimWhitespaceRequest](#trimwhitespacerequest) | Trims cells of whitespace (such as spaces, tabs, or new lines). |
| `deleteDuplicates` | [DeleteDuplicatesRequest](#deleteduplicatesrequest) | Removes rows containing duplicate values in specified columns of a cell range. |
| `updateEmbeddedObjectBorder` | [UpdateEmbeddedObjectBorderRequest](#updateembeddedobjectborderrequest) | Updates an embedded object's border. |
| `addSlicer` | [AddSlicerRequest](#addslicerrequest) | Adds a slicer. |
| `updateSlicerSpec` | [UpdateSlicerSpecRequest](#updateslicerspecrequest) | Updates a slicer's specifications. |
| `addDataSource` | [AddDataSourceRequest](#adddatasourcerequest) | Adds a data source. |
| `updateDataSource` | [UpdateDataSourceRequest](#updatedatasourcerequest) | Updates a data source. |
| `deleteDataSource` | [DeleteDataSourceRequest](#deletedatasourcerequest) | Deletes a data source. |
| `refreshDataSource` | [RefreshDataSourceRequest](#refreshdatasourcerequest) | Refreshes one or multiple data sources and associated dbobjects. |
| `cancelDataSourceRefresh` | [CancelDataSourceRefreshRequest](#canceldatasourcerefreshrequest) | Cancels refreshes of one or multiple data sources and associated dbobjects. |
| `addTable` | [AddTableRequest](#addtablerequest) | Adds a table. |
| `updateTable` | [UpdateTableRequest](#updatetablerequest) | Updates a table. |
| `deleteTable` | [DeleteTableRequest](#deletetablerequest) | A request for deleting a table. |
| `insertComment` | [InsertCommentRequest](#insertcommentrequest) | Inserts a CommentThread into the spreadsheet. Developer Preview. |
| `addCommentReply` | [AddCommentReplyRequest](#addcommentreplyrequest) | Adds a reply to a CommentThread. Developer Preview. |
| `updateCommentPost` | [UpdateCommentPostRequest](#updatecommentpostrequest) | Updates an existing post of a CommentThread. Developer Preview. |
| `deleteComment` | [DeleteCommentRequest](#deletecommentrequest) | Deletes a CommentThread. Developer Preview. |
| `deleteCommentReply` | [DeleteCommentReplyRequest](#deletecommentreplyrequest) | Deletes a reply Post from a CommentThread. Developer Preview. |
## UpdateSpreadsheetPropertiesRequest
Updates properties of a spreadsheet.
| Field | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `properties` | [SpreadsheetProperties](#spreadsheetproperties) | The properties to update. |
## FieldMask
`FieldMask` represents a set of symbolic field paths.
| Field | Type | Description |
| ------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paths` \* | `string`\[] | The set of field mask paths. Each path is a dot-separated sequence of camelCase field names, e.g. 'userEnteredValue' or 'userEnteredFormat.horizontalAlignment'. |
## UpdateSheetPropertiesRequest
Updates properties of the sheet with the specified sheetId.
| Field | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `properties` | [SheetProperties](#sheetproperties) | The properties to update. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## UpdateDimensionPropertiesRequest
Updates properties of dimensions within the specified range.
| Field | Type | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `dataSourceSheetRange` | [DataSourceSheetDimensionRange](#datasourcesheetdimensionrange) | The columns on a data source sheet to update. |
| `properties` | [DimensionProperties](#dimensionproperties) | Properties to update. |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The rows or columns to update. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## DataSourceSheetDimensionRange
A range along a single dimension on a DATA\_SOURCE sheet.
| Field | Type | Description |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------ |
| `columnReferences` | [DataSourceColumnReference](#datasourcecolumnreference)\[] | The columns on the data source sheet. |
| `sheetId` | `integer` | The ID of the data source sheet the range is on. |
## UpdateNamedRangeRequest
Updates properties of the named range with the specified namedRangeId.
| Field | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `namedRange` | [NamedRange](#namedrange) | The named range to update with the new properties. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## RepeatCellRequest
Updates all cells in the range to the values in the given Cell object. Only the fields listed in the fields field are updated; others are unchanged. If writing a cell with a formula, the formula's ranges will automatically increment for each field in the range. For example, if writing a cell with formula `=A1` into range B2:C4, B2 would be `=A1`, B3 would be `=A2`, B4 would be `=A3`, C2 would be `=B1`, C3 would be `=B2`, C4 would be `=B3`. To keep the formula's ranges static, use the `$` indicator. For example, use the formula `=$A$1` to prevent both the row and the column from incrementing.
| Field | Type | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `cell` | [CellData](#celldata) | The data to write. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to repeat the cell in. |
## AddNamedRangeRequest
Adds a named range to the spreadsheet.
| Field | Type | Description |
| ------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namedRange` | [NamedRange](#namedrange) | The named range to add. The namedRangeId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of a range that already exists.) |
## DeleteNamedRangeRequest
Removes the named range with the given ID from the spreadsheet.
| Field | Type | Description |
| -------------- | -------- | ------------------------------------ |
| `namedRangeId` | `string` | The ID of the named range to delete. |
## AddSheetRequest
Adds a new sheet. When a sheet is added at a given index, all subsequent sheets' indexes are incremented. To add an object sheet, use AddChartRequest instead and specify EmbeddedObjectPosition.sheetId or EmbeddedObjectPosition.newSheet.
| Field | Type | Description |
| ------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | [SheetProperties](#sheetproperties) | The properties the new sheet should have. All properties are optional. The sheetId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of a sheet that already exists.) |
## DeleteSheetRequest
Deletes the requested sheet.
| Field | Type | Description |
| --------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `sheetId` | `integer` | The ID of the sheet to delete. If the sheet is of DATA\_SOURCE type, the associated DataSource is also deleted. |
## AutoFillRequest
Fills in more data based on existing data.
| Field | Type | Description |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to autofill. This will examine the range and detect the location that has data and automatically fill that data in to the rest of the range. |
| `sourceAndDestination` | [SourceAndDestination](#sourceanddestination) | The source and destination areas to autofill. This explicitly lists the source of the autofill and where to extend that data. |
| `useAlternateSeries` | `boolean` | True if we should generate data with the "alternate" series. This differs based on the type and amount of source data. |
## SourceAndDestination
A combination of a source range and how to extend that source.
| Field | Type | Description |
| ------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The location of the data to use as the source of the autofill. |
| `dimension` | [Dimension](/charter/charter/packs/gsheets/values/objects#dimension) | The dimension that data should be filled into. |
| `fillLength` | `integer` | The number of rows or columns that data should be filled into. Positive numbers expand beyond the last row or last column of the source. Negative numbers expand before the first row or first column of the source. |
## CutPasteRequest
Moves data from the source to the destination.
| Field | Type | Description |
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `destination` | [GridCoordinate](#gridcoordinate) | The top-left coordinate where the data should be pasted. |
| `pasteType` | [PasteType](#pastetype) | What kind of data to paste. All the source data will be cut, regardless of what is pasted. |
| `source` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The source data to cut. |
## CopyPasteRequest
Copies data from the source to the destination.
| Field | Type | Description |
| ------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `destination` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The location to paste to. If the range covers a span that's a multiple of the source's height or width, then the data will be repeated to fill in the destination range. If the range is smaller than the source range, the entire source data will still be copied (beyond the end of the destination range). |
| `pasteOrientation` | [PasteOrientation](#pasteorientation) | How that data should be oriented when pasting. |
| `pasteType` | [PasteType](#pastetype) | What kind of data to paste. |
| `source` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The source range to copy. |
## MergeCellsRequest
Merges all cells in the range.
| Field | Type | Description |
| ----------- | ------------------------------------------------------------ | ------------------------------- |
| `mergeType` | [MergeType](#mergetype) | How the cells should be merged. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range of cells to merge. |
## UnmergeCellsRequest
Unmerges cells in the given range.
| Field | Type | Description |
| ------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range within which all cells should be unmerged. If the range spans multiple merges, all will be unmerged. The range must not partially span any merge. |
## UpdateBordersRequest
Updates the borders of a range. If a field is not set in the request, that means the border remains as-is. For example, with two subsequent UpdateBordersRequest: 1. range: A1:A5 `{ top: RED, bottom: WHITE }` 2. range: A1:A5 `{ left: BLUE }` That would result in A1:A5 having a borders of `{ top: RED, bottom: WHITE, left: BLUE }`. If you want to clear a border, explicitly set the style to NONE.
| Field | Type | Description |
| ----------------- | ------------------------------------------------------------ | ---------------------------------------------- |
| `right` | [Border](#border) | The border to put at the right of the range. |
| `left` | [Border](#border) | The border to put at the left of the range. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range whose borders should be updated. |
| `innerVertical` | [Border](#border) | The vertical border to put within the range. |
| `bottom` | [Border](#border) | The border to put at the bottom of the range. |
| `innerHorizontal` | [Border](#border) | The horizontal border to put within the range. |
| `top` | [Border](#border) | The border to put at the top of the range. |
## UpdateCellsRequest
Updates all cells in a range with new data.
| Field | Type | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows` | [RowData](#rowdata)\[] | The data to write. |
| `start` | [GridCoordinate](#gridcoordinate) | The coordinate to start writing data at. Any number of rows and columns (including a different number of columns per row) may be written. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to write data to. If the data in rows does not cover the entire requested range, the fields matching those set in fields will be cleared. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## AddFilterViewRequest
Adds a filter view.
| Field | Type | Description |
| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter` | [FilterView](#filterview) | The filter to add. The filterViewId field is optional. If one is not set, an ID will be randomly generated. (It is an error to specify the ID of a filter that already exists.) |
## AppendCellsRequest
Adds new cells after the last row with data in a sheet, inserting new rows into the sheet if necessary.
| Field | Type | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableId` | `string` | The ID of the table to append data to. The data will be only appended to the table body. This field also takes precedence over the `sheet_id` field. |
| `rows` | [RowData](#rowdata)\[] | The data to append. |
| `sheetId` | `integer` | The sheet ID to append the data to. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## ClearBasicFilterRequest
Clears the basic filter, if any exists on the sheet.
| Field | Type | Description |
| --------- | --------- | --------------------------------------------------------- |
| `sheetId` | `integer` | The sheet ID on which the basic filter should be cleared. |
## DeleteDimensionRequest
Deletes the dimensions from the sheet.
| Field | Type | Description |
| ------- | ---------------------------------------------------------------------- | ---------------------------------------- |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The dimensions to delete from the sheet. |
## DeleteEmbeddedObjectRequest
Deletes the embedded object with the given ID.
| Field | Type | Description |
| ---------- | --------- | ---------------------------------------- |
| `objectId` | `integer` | The ID of the embedded object to delete. |
## DeleteFilterViewRequest
Deletes a particular filter view.
| Field | Type | Description |
| ---------- | --------- | ------------------------------- |
| `filterId` | `integer` | The ID of the filter to delete. |
## DuplicateFilterViewRequest
Duplicates a particular filter view.
| Field | Type | Description |
| ---------- | --------- | -------------------------------------- |
| `filterId` | `integer` | The ID of the filter being duplicated. |
## DuplicateSheetRequest
Duplicates the contents of a sheet.
| Field | Type | Description |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceSheetId` | `integer` | The sheet to duplicate. If the source sheet is of DATA\_SOURCE type, its backing DataSource is also duplicated and associated with the new copy of the sheet. No data execution is triggered, the grid data of this sheet is also copied over but only available after the batch request completes. |
| `insertSheetIndex` | `integer` | The zero-based index where the new sheet should be inserted. The index of all sheets after this are incremented. |
| `newSheetId` | `integer` | If set, the ID of the new sheet. If not set, an ID is chosen. If set, the ID must not conflict with any existing sheet ID. If set, it must be non-negative. ≥ 0 |
| `newSheetName` | `string` | The name of the new sheet. If empty, a new name is chosen for you. |
## FindReplaceRequest
Finds and replaces data in cells over a range, sheet, or all sheets.
| Field | Type | Description |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matchCase` | `boolean` | True if the search is case sensitive. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to find/replace over. |
| `sheetId` | `integer` | The sheet to find/replace over. |
| `find` | `string` | The value to search. |
| `searchByRegex` | `boolean` | True if the find value is a regex. The regular expression and replacement should follow Java regex rules at [https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). The replacement string is allowed to refer to capturing groups. For example, if one cell has the contents `"Google Sheets"` and another has `"Google Docs"`, then searching for `"o.* (.*)"` with a replacement of `"$1 Rocks"` would change the contents of the cells to `"GSheets Rocks"` and `"GDocs Rocks"` respectively. |
| `includeFormulas` | `boolean` | True if the search should include cells with formulas. False to skip cells with formulas. |
| `replacement` | `string` | The value to use as the replacement. |
| `allSheets` | `boolean` | True to find/replace over all sheets. |
| `matchEntireCell` | `boolean` | True if the find value should match the entire cell. |
## InsertDimensionRequest
Inserts rows or columns in a sheet at a particular index.
| Field | Type | Description |
| ------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inheritFromBefore` | `boolean` | Whether dimension properties should be extended from the dimensions before or after the newly inserted dimensions. True to inherit from the dimensions before (in which case the start index must be greater than 0), and false to inherit from the dimensions after. For example, if row index 0 has red background and row index 1 has a green background, then inserting 2 rows at index 1 can inherit either the green or red background. If `inheritFromBefore` is true, the two new rows will be red (because the row before the insertion point was red), whereas if `inheritFromBefore` is false, the two new rows will be green (because the row after the insertion point was green). |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The dimensions to insert. Both the start and end indexes must be bounded. |
## InsertRangeRequest
Inserts cells into a range, shifting the existing cells over or down.
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shiftDimension` | [Dimension](/charter/charter/packs/gsheets/values/objects#dimension) | The dimension which will be shifted when inserting cells. If ROWS, existing cells will be shifted down. If COLUMNS, existing cells will be shifted right. |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to insert new cells into. The range is constrained to the current sheet boundaries. |
## MoveDimensionRequest
Moves one or more rows or columns.
| Field | Type | Description |
| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The source dimensions to move. |
| `destinationIndex` | `integer` | The zero-based start index of where to move the source data to, based on the coordinates *before* the source data is removed from the grid. Existing data will be shifted down or right (depending on the dimension) to make room for the moved dimensions. The source dimensions are removed from the grid, so the the data may end up in a different index than specified. For example, given `A1..A5` of `0, 1, 2, 3, 4` and wanting to move `"1"` and `"2"` to between `"3"` and `"4"`, the source would be `ROWS [1..3)`,and the destination index would be `"4"` (the zero-based index of row 5). The end result would be `A1..A5` of `0, 3, 1, 2, 4`. |
## UpdateEmbeddedObjectPositionRequest
Update an embedded object's position (such as a moving or resizing a chart or image).
| Field | Type | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `objectId` | `integer` | The ID of the object to moved. |
| `newPosition` | [EmbeddedObjectPosition](#embeddedobjectposition) | An explicit position to move the embedded object to. If newPosition.sheetId is set, a new sheet with that ID will be created. If newPosition.newSheet is set to true, a new sheet will be created with an ID that will be chosen for you. |
## PasteDataRequest
Inserts data into the spreadsheet starting at the specified coordinate.
| Field | Type | Description |
| ------------ | --------------------------------- | ------------------------------------------------------------- |
| `data` | `string` | The data to insert. |
| `type` | [PasteType](#pastetype) | How the data should be pasted. |
| `coordinate` | [GridCoordinate](#gridcoordinate) | The coordinate at which the data should start being inserted. |
| `delimiter` | `string` | The delimiter in the data. |
| `html` | `boolean` | True if the data is HTML. |
## TextToColumnsRequest
Splits a column of text into multiple columns, based on a delimiter in each cell.
| Field | Type | Description |
| --------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| `delimiterType` | [DelimiterType](#delimitertype) | The delimiter type to use. |
| `source` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The source data range. This must span exactly one column. |
| `delimiter` | `string` | The delimiter to use. Used only if delimiterType is CUSTOM. |
## UpdateFilterViewRequest
Updates properties of the filter view.
| Field | Type | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `filter` | [FilterView](#filterview) | The new properties of the filter view. |
## DeleteRangeRequest
Deletes a range of cells, shifting other cells into the deleted area.
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range of cells to delete. |
| `shiftDimension` | [Dimension](/charter/charter/packs/gsheets/values/objects#dimension) | The dimension from which deleted cells will be replaced with. If ROWS, existing cells will be shifted upward to replace the deleted cells. If COLUMNS, existing cells will be shifted left to replace the deleted cells. |
## AppendDimensionRequest
Appends rows or columns to the end of a sheet.
| Field | Type | Description |
| ----------- | ------------------------------------------------------------ | ------------------------------------------- |
| `sheetId` | `integer` | The sheet to append rows or columns to. |
| `dimension` | [Dimension](/charter/charter/packs/gsheets/values/objects#dimension) | Whether rows or columns should be appended. |
| `length` | `integer` | The number of rows or columns to append. |
## AddConditionalFormatRuleRequest
Adds a new conditional format rule at the given index. All subsequent rules' indexes are incremented.
| Field | Type | Description |
| ------- | ----------------------------------------------- | ------------------------------------------------------- |
| `index` | `integer` | The zero-based index where the rule should be inserted. |
| `rule` | [ConditionalFormatRule](#conditionalformatrule) | The rule to add. |
## UpdateConditionalFormatRuleRequest
Updates a conditional format rule at the given index, or moves a conditional format rule to another index.
| Field | Type | Description |
| ---------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `newIndex` | `integer` | The zero-based new index the rule should end up at. |
| `rule` | [ConditionalFormatRule](#conditionalformatrule) | The rule that should replace the rule at the given index. |
| `sheetId` | `integer` | The sheet of the rule to move. Required if new\_index is set, unused otherwise. |
| `index` | `integer` | The zero-based index of the rule that should be replaced or moved. |
## DeleteConditionalFormatRuleRequest
Deletes a conditional format rule at the given index. All subsequent rules' indexes are decremented.
| Field | Type | Description |
| --------- | --------- | ----------------------------------------------- |
| `sheetId` | `integer` | The sheet the rule is being deleted from. |
| `index` | `integer` | The zero-based index of the rule to be deleted. |
## SortRangeRequest
Sorts data in rows based on a sort order per column.
| Field | Type | Description |
| ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to sort. |
| `sortSpecs` | [SortSpec](#sortspec)\[] | The sort order per column. Later specifications are used when values are equal in the earlier specifications. |
## SetDataValidationRequest
Sets a data validation rule to every cell in the range. To clear validation in a range, call this with no rule specified.
| Field | Type | Description |
| ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range the data validation rule should apply to. |
| `rule` | [DataValidationRule](#datavalidationrule) | The data validation rule to set on each cell in the range, or empty to clear the data validation in the range. |
| `filteredRowsIncluded` | `boolean` | Optional. If true, the data validation rule will be applied to the filtered rows as well. |
## SetBasicFilterRequest
Sets the basic filter associated with a sheet.
| Field | Type | Description |
| -------- | --------------------------- | ------------------ |
| `filter` | [BasicFilter](#basicfilter) | The filter to set. |
## AddProtectedRangeRequest
Adds a new protected range.
| Field | Type | Description |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `protectedRange` | [ProtectedRange](#protectedrange) | The protected range to be added. The protectedRangeId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of a range that already exists.) |
## UpdateProtectedRangeRequest
Updates an existing protected range with the specified protectedRangeId.
| Field | Type | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `protectedRange` | [ProtectedRange](#protectedrange) | The protected range to update with the new properties. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## DeleteProtectedRangeRequest
Deletes the protected range with the given ID.
| Field | Type | Description |
| ------------------ | --------- | ---------------------------------------- |
| `protectedRangeId` | `integer` | The ID of the protected range to delete. |
## AutoResizeDimensionsRequest
Automatically resizes one or more dimensions based on the contents of the cells in that dimension.
| Field | Type | Description |
| --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| `dimensions` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The dimensions to automatically resize. |
| `dataSourceSheetDimensions` | [DataSourceSheetDimensionRange](#datasourcesheetdimensionrange) | The dimensions on a data source sheet to automatically resize. |
## AddChartRequest
Adds a chart to a sheet in the spreadsheet.
| Field | Type | Description |
| ------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chart` | [EmbeddedChart](#embeddedchart) | The chart that should be added to the spreadsheet, including the position where it should be placed. The chartId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of an embedded object that already exists.) |
## UpdateChartSpecRequest
Updates a chart's specifications. (This does not move or resize a chart. To move or resize a chart, use UpdateEmbeddedObjectPositionRequest.)
| Field | Type | Description |
| --------- | ----------------------- | ---------------------------------------- |
| `chartId` | `integer` | The ID of the chart to update. |
| `spec` | [ChartSpec](#chartspec) | The specification to apply to the chart. |
## UpdateBandingRequest
Updates properties of the supplied banded range.
| Field | Type | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `bandedRange` | [BandedRange](#bandedrange) | The banded range to update with the new properties. |
## AddBandingRequest
Adds a new banded range to the spreadsheet.
| Field | Type | Description |
| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bandedRange` | [BandedRange](#bandedrange) | The banded range to add. The bandedRangeId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of a range that already exists.) |
## DeleteBandingRequest
Removes the banded range with the given ID from the spreadsheet.
| Field | Type | Description |
| --------------- | --------- | ------------------------------------- |
| `bandedRangeId` | `integer` | The ID of the banded range to delete. |
## CreateDeveloperMetadataRequest
A request to create developer metadata.
| Field | Type | Description |
| ------------------- | --------------------------------------- | --------------------------------- |
| `developerMetadata` | [DeveloperMetadata](#developermetadata) | The developer metadata to create. |
## UpdateDeveloperMetadataRequest
A request to update properties of developer metadata. Updates the properties of the developer metadata selected by the filters to the values provided in the DeveloperMetadata resource. Callers must specify the properties they wish to update in the fields parameter, as well as specify at least one DataFilter matching the metadata they wish to update.
| Field | Type | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `developerMetadata` | [DeveloperMetadata](#developermetadata) | The value that all metadata matched by the data filters will be updated to. |
| `dataFilters` | [DataFilter](/charter/charter/packs/gsheets/values/objects#datafilter)\[] | The filters matching the developer metadata entries to update. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## DeleteDeveloperMetadataRequest
A request to delete developer metadata.
| Field | Type | Description |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `dataFilter` | [DataFilter](/charter/charter/packs/gsheets/values/objects#datafilter) | The data filter describing the criteria used to select which developer metadata entry to delete. |
## RandomizeRangeRequest
Randomizes the order of the rows in a range.
| Field | Type | Description |
| ------- | ------------------------------------------------------------ | ----------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to randomize. |
## AddDimensionGroupRequest
Creates a group over the specified range. If the requested range is a superset of the range of an existing group G, then the depth of G is incremented and this new group G' has the depth of that group. For example, a group \[C:D, depth 1] + \[B:E] results in groups \[B:E, depth 1] and \[C:D, depth 2]. If the requested range is a subset of the range of an existing group G, then the depth of the new group G' becomes one greater than the depth of G. For example, a group \[B:E, depth 1] + \[C:D] results in groups \[B:E, depth 1] and \[C:D, depth 2]. If the requested range starts before and ends within, or starts within and ends after, the range of an existing group G, then the range of the existing group G becomes the union of the ranges, and the new group G' has depth one greater than the depth of G and range as the intersection of the ranges. For example, a group \[B:D, depth 1] + \[C:E] results in groups \[B:E, depth 1] and \[C:D, depth 2].
| Field | Type | Description |
| ------- | ---------------------------------------------------------------------- | --------------------------------------- |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The range over which to create a group. |
## DeleteDimensionGroupRequest
Deletes a group over the specified range by decrementing the depth of the dimensions in the range. For example, assume the sheet has a depth-1 group over B:E and a depth-2 group over C:D. Deleting a group over D:E leaves the sheet with a depth-1 group over B:D and a depth-2 group over C:C.
| Field | Type | Description |
| ------- | ---------------------------------------------------------------------- | ------------------------------------- |
| `range` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange) | The range of the group to be deleted. |
## UpdateDimensionGroupRequest
Updates the state of the specified group.
| Field | Type | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `dimensionGroup` | [DimensionGroup](#dimensiongroup) | The group whose state should be updated. The range and depth of the group should specify a valid group on the sheet, and all other fields updated. |
## TrimWhitespaceRequest
Trims the whitespace (such as spaces, tabs, or new lines) in every cell in the specified range. This request removes all whitespace from the start and end of each cell's text, and reduces any subsequence of remaining whitespace characters to a single space. If the resulting trimmed text starts with a '+' or '=' character, the text remains as a string value and isn't interpreted as a formula.
| Field | Type | Description |
| ------- | ------------------------------------------------------------ | ------------------------------ |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range whose cells to trim. |
## DeleteDuplicatesRequest
Removes rows within this range that contain values in the specified columns that are duplicates of values in any previous row. Rows with identical values but different letter cases, formatting, or formulas are considered to be duplicates. This request also removes duplicate rows hidden from view (for example, due to a filter). When removing duplicates, the first instance of each duplicate row scanning from the top downwards is kept in the resulting range. Content outside of the specified range isn't removed, and rows considered duplicates do not have to be adjacent to each other in the range.
| Field | Type | Description |
| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `range` | [GridRange](/charter/charter/packs/gsheets/values/objects#gridrange) | The range to remove duplicates rows from. |
| `comparisonColumns` | [DimensionRange](/charter/charter/packs/gsheets/values/objects#dimensionrange)\[] | The columns in the range to analyze for duplicate values. If no columns are selected then all columns are analyzed for duplicates. |
## UpdateEmbeddedObjectBorderRequest
Updates an embedded object's border property.
| Field | Type | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `border` | [EmbeddedObjectBorder](#embeddedobjectborder) | The border that applies to the embedded object. |
| `objectId` | `integer` | The ID of the embedded object to update. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## AddSlicerRequest
Adds a slicer to a sheet in the spreadsheet.
| Field | Type | Description |
| -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slicer` | [Slicer](#slicer) | The slicer that should be added to the spreadsheet, including the position where it should be placed. The slicerId field is optional; if one is not set, an id will be randomly generated. (It is an error to specify the ID of a slicer that already exists.) |
## UpdateSlicerSpecRequest
Updates a slicer's specifications. (This does not move or resize a slicer. To move or resize a slicer use UpdateEmbeddedObjectPositionRequest.
| Field | Type | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `slicerId` | `integer` | The id of the slicer to update. |
| `spec` | [SlicerSpec](#slicerspec) | The specification to apply to the slicer. |
## AddDataSourceRequest
Adds a data source. After the data source is added successfully, an associated DATA\_SOURCE sheet is created and an execution is triggered to refresh the sheet to read data from the data source. The request requires an additional `bigquery.readonly` OAuth scope if you are adding a BigQuery data source.
| Field | Type | Description |
| ------------ | ------------------------- | ----------------------- |
| `dataSource` | [DataSource](#datasource) | The data source to add. |
## UpdateDataSourceRequest
Updates a data source. After the data source is updated successfully, an execution is triggered to refresh the associated DATA\_SOURCE sheet to read data from the updated data source. The request requires an additional `bigquery.readonly` OAuth scope if you are updating a BigQuery data source.
| Field | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `dataSource` | [DataSource](#datasource) | The data source to update. |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
## DeleteDataSourceRequest
Deletes a data source. The request also deletes the associated data source sheet, and unlinks all associated data source objects.
| Field | Type | Description |
| -------------- | -------- | ------------------------------------ |
| `dataSourceId` | `string` | The ID of the data source to delete. |
## RefreshDataSourceRequest
Refreshes one or multiple data source objects in the spreadsheet by the specified references. The request requires an additional `bigquery.readonly` OAuth scope if you are refreshing a BigQuery data source. If there are multiple refresh requests referencing the same data source objects in one batch, only the last refresh request is processed, and all those requests will have the same response accordingly.
| Field | Type | Description |
| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `references` | [DataSourceObjectReferences](#datasourceobjectreferences) | References to data source objects to refresh. |
| `dataSourceId` | `string` | Reference to a DataSource. If specified, refreshes all associated data source objects for the data source. |
| `isAll` | `boolean` | Refreshes all existing data source objects in the spreadsheet. |
| `force` | `boolean` | Refreshes the data source objects regardless of the current state. If not set and a referenced data source object was in error state, the refresh will fail immediately. |
## DataSourceObjectReferences
A list of references to data source objects.
| Field | Type | Description |
| ------------ | ---------------------------------------------------------- | --------------- |
| `references` | [DataSourceObjectReference](#datasourceobjectreference)\[] | The references. |
## DataSourceObjectReference
Reference to a data source object.
| Field | Type | Description |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------ |
| `chartId` | `integer` | References to a data source chart. |
| `dataSourceTableAnchorCell` | [GridCoordinate](#gridcoordinate) | References to a DataSourceTable anchored at the cell. |
| `dataSourceFormulaCell` | [GridCoordinate](#gridcoordinate) | References to a cell containing DataSourceFormula. |
| `sheetId` | `string` | References to a DATA\_SOURCE sheet. |
| `dataSourcePivotTableAnchorCell` | [GridCoordinate](#gridcoordinate) | References to a data source PivotTable anchored at the cell. |
## CancelDataSourceRefreshRequest
Cancels one or multiple refreshes of data source objects in the spreadsheet by the specified references. The request requires an additional `bigquery.readonly` OAuth scope if you are cancelling a refresh on a BigQuery data source.
| Field | Type | Description |
| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `isAll` | `boolean` | Cancels all existing data source object refreshes for all data sources in the spreadsheet. |
| `references` | [DataSourceObjectReferences](#datasourceobjectreferences) | References to data source objects whose refreshes are to be cancelled. |
| `dataSourceId` | `string` | Reference to a DataSource. If specified, cancels all associated data source object refreshes for this data source. |
## AddTableRequest
Adds a new table to the spreadsheet.
| Field | Type | Description |
| ------- | --------------- | --------------------------- |
| `table` | [Table](#table) | Required. The table to add. |
## UpdateTableRequest
Updates a table in the spreadsheet.
| Field | Type | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `fields` | [FieldMask](#fieldmask)
field\_mask | Field mask paths |
| `table` | [Table](#table) | Required. The table to update. |
## DeleteTableRequest
Removes the table with the given ID from the spreadsheet.
| Field | Type | Description |
| --------- | -------- | ------------------------------ |
| `tableId` | `string` | The ID of the table to delete. |
## InsertCommentRequest
Inserts a CommentThread into the spreadsheet.
| Field | Type | Description |
| ---------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | `string` | The text of the comment, as plain text. This field cannot be empty, and must not exceed 2048 UTF-8 code units. |
| `assigneeEmailAddress` | `string` | Optional. The email address of the assignee of the comment. Leave empty for a non-assigned comment. May not exceed 2048 UTF-8 code units. |
| `coordinate` | [GridCoordinate](#gridcoordinate) | The GridCoordinate in the sheet that is tied to this comment. |
## AddCommentReplyRequest
Inserts a reply Post into a CommentThread.
| Field | Type | Description |
| ----------- | ------------- | ------------------------------------------------ |
| `commentId` | `string` | The ID of the CommentThread to add the reply to. |
| `post` | [Post](#post) | The Post representing the reply. |
## UpdateCommentPostRequest
Updates a Post in a CommentThread.
| Field | Type | Description |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `commentId` | `string` | The ID of the CommentThread which the post belongs to. |
| `postId` | `string` | The ID of the post being updated. |
| `content` | `string` | The new text of the comment, as plain text. This field cannot be empty, and must not exceed 2048 UTF-8 code units. |
## DeleteCommentRequest
Deletes a CommentThread.
| Field | Type | Description |
| ----------- | -------- | -------------------------------------------------- |
| `commentId` | `string` | The ID of the CommentThread that is being deleted. |
## DeleteCommentReplyRequest
Deletes a reply Post from a CommentThread.
| Field | Type | Description |
| ----------- | -------- | ------------------------------------------------------ |
| `commentId` | `string` | The ID of the CommentThread which the post belongs to. |
| `postId` | `string` | The ID of the reply Post being deleted. |
## CopySheetToAnotherSpreadsheetRequest
The request to copy a sheet across spreadsheets.
| Field | Type | Description |
| -------------------------------------------------------------------------------- | -------- | ----------------------------------------------- |
| `destinationSpreadsheetId` \* | `string` | The ID of the spreadsheet to copy the sheet to. |
## CommentsViewMode
| Value |
| ----------------------------------------------- |
| `COMMENTS_VIEW_MODE_UNSPECIFIED` |
| `COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS` |
| `COMMENTS_VIEW_MODE_OMITTED` |
| `COMMENTS_VIEW_MODE_INCLUDED` |
## BaselineValueFormatComparisonType
| Value |
| --------------------------- |
| `COMPARISON_TYPE_UNDEFINED` |
| `ABSOLUTE_DIFFERENCE` |
| `PERCENTAGE_DIFFERENCE` |
## BasicChartSeriesTargetAxis
| Value |
| --------------------------------------- |
| `BASIC_CHART_AXIS_POSITION_UNSPECIFIED` |
| `BOTTOM_AXIS` |
| `LEFT_AXIS` |
| `RIGHT_AXIS` |
## BasicChartSeriesType
| Value |
| ------------------------------ |
| `BASIC_CHART_TYPE_UNSPECIFIED` |
| `BAR` |
| `LINE` |
| `AREA` |
| `COLUMN` |
| `SCATTER` |
| `COMBO` |
| `STEPPED_AREA` |
## BasicChartSpecCompareMode
| Value |
| -------------------------------------- |
| `BASIC_CHART_COMPARE_MODE_UNSPECIFIED` |
| `DATUM` |
| `CATEGORY` |
## BasicChartSpecLegendPosition
| Value |
| ----------------------------------------- |
| `BASIC_CHART_LEGEND_POSITION_UNSPECIFIED` |
| `BOTTOM_LEGEND` |
| `LEFT_LEGEND` |
| `RIGHT_LEGEND` |
| `TOP_LEGEND` |
| `NO_LEGEND` |
## BasicChartSpecStackedType
| Value |
| -------------------------------------- |
| `BASIC_CHART_STACKED_TYPE_UNSPECIFIED` |
| `NOT_STACKED` |
| `STACKED` |
| `PERCENT_STACKED` |
## BooleanConditionType
| Value |
| ---------------------------- |
| `CONDITION_TYPE_UNSPECIFIED` |
| `NUMBER_GREATER` |
| `NUMBER_GREATER_THAN_EQ` |
| `NUMBER_LESS` |
| `NUMBER_LESS_THAN_EQ` |
| `NUMBER_EQ` |
| `NUMBER_NOT_EQ` |
| `NUMBER_BETWEEN` |
| `NUMBER_NOT_BETWEEN` |
| `TEXT_CONTAINS` |
| `TEXT_NOT_CONTAINS` |
| `TEXT_STARTS_WITH` |
| `TEXT_ENDS_WITH` |
| `TEXT_EQ` |
| `TEXT_IS_EMAIL` |
| `TEXT_IS_URL` |
| `DATE_EQ` |
| `DATE_BEFORE` |
| `DATE_AFTER` |
| `DATE_ON_OR_BEFORE` |
| `DATE_ON_OR_AFTER` |
| `DATE_BETWEEN` |
| `DATE_NOT_BETWEEN` |
| `DATE_IS_VALID` |
| `ONE_OF_RANGE` |
| `ONE_OF_LIST` |
| `BLANK` |
| `NOT_BLANK` |
| `CUSTOM_FORMULA` |
| `BOOLEAN` |
| `TEXT_NOT_EQ` |
| `DATE_NOT_EQ` |
| `FILTER_EXPRESSION` |
## BorderStyle
| Value |
| ------------------- |
| `STYLE_UNSPECIFIED` |
| `DOTTED` |
| `DASHED` |
| `SOLID` |
| `SOLID_MEDIUM` |
| `SOLID_THICK` |
| `NONE` |
| `DOUBLE` |
## BubbleChartSpecLegendPosition
| Value |
| ------------------------------------------ |
| `BUBBLE_CHART_LEGEND_POSITION_UNSPECIFIED` |
| `BOTTOM_LEGEND` |
| `LEFT_LEGEND` |
| `RIGHT_LEGEND` |
| `TOP_LEGEND` |
| `NO_LEGEND` |
| `INSIDE_LEGEND` |
## CellFormatHyperlinkDisplayType
| Value |
| ------------------------------------ |
| `HYPERLINK_DISPLAY_TYPE_UNSPECIFIED` |
| `LINKED` |
| `PLAIN_TEXT` |
## CellFormatTextDirection
| Value |
| ---------------------------- |
| `TEXT_DIRECTION_UNSPECIFIED` |
| `LEFT_TO_RIGHT` |
| `RIGHT_TO_LEFT` |
## ChartAxisViewWindowOptionsViewWindowMode
| Value |
| ------------------------------ |
| `DEFAULT_VIEW_WINDOW_MODE` |
| `VIEW_WINDOW_MODE_UNSUPPORTED` |
| `EXPLICIT` |
| `PRETTY` |
## ChartDateTimeRuleType
| Value |
| --------------------------------------- |
| `CHART_DATE_TIME_RULE_TYPE_UNSPECIFIED` |
| `SECOND` |
| `MINUTE` |
| `HOUR` |
| `HOUR_MINUTE` |
| `HOUR_MINUTE_AMPM` |
| `DAY_OF_WEEK` |
| `DAY_OF_YEAR` |
| `DAY_OF_MONTH` |
| `DAY_MONTH` |
| `MONTH` |
| `QUARTER` |
| `YEAR` |
| `YEAR_MONTH` |
| `YEAR_QUARTER` |
| `YEAR_MONTH_DAY` |
## ChartSpecHiddenDimensionStrategy
| Value |
| --------------------------------------------- |
| `CHART_HIDDEN_DIMENSION_STRATEGY_UNSPECIFIED` |
| `SKIP_HIDDEN_ROWS_AND_COLUMNS` |
| `SKIP_HIDDEN_ROWS` |
| `SKIP_HIDDEN_COLUMNS` |
| `SHOW_ALL` |
## ConditionValueRelativeDate
| Value |
| --------------------------- |
| `RELATIVE_DATE_UNSPECIFIED` |
| `PAST_YEAR` |
| `PAST_MONTH` |
| `PAST_WEEK` |
| `YESTERDAY` |
| `TODAY` |
| `TOMORROW` |
## DataLabelPlacement
| Value |
| ---------------------------------- |
| `DATA_LABEL_PLACEMENT_UNSPECIFIED` |
| `CENTER` |
| `LEFT` |
| `RIGHT` |
| `ABOVE` |
| `BELOW` |
| `INSIDE_END` |
| `INSIDE_BASE` |
| `OUTSIDE_END` |
## DataLabelType
| Value |
| ----------------------------- |
| `DATA_LABEL_TYPE_UNSPECIFIED` |
| `NONE` |
| `DATA` |
| `CUSTOM` |
## DataSourceTableColumnSelectionType
| Value |
| ----------------------------------------------------- |
| `DATA_SOURCE_TABLE_COLUMN_SELECTION_TYPE_UNSPECIFIED` |
| `SELECTED` |
| `SYNC_ALL` |
## DateTimeRuleType
| Value |
| --------------------------------- |
| `DATE_TIME_RULE_TYPE_UNSPECIFIED` |
| `SECOND` |
| `MINUTE` |
| `HOUR` |
| `HOUR_MINUTE` |
| `HOUR_MINUTE_AMPM` |
| `DAY_OF_WEEK` |
| `DAY_OF_YEAR` |
| `DAY_OF_MONTH` |
| `DAY_MONTH` |
| `MONTH` |
| `QUARTER` |
| `YEAR` |
| `YEAR_MONTH` |
| `YEAR_QUARTER` |
| `YEAR_MONTH_DAY` |
## DelimiterType
| Value |
| ---------------------------- |
| `DELIMITER_TYPE_UNSPECIFIED` |
| `COMMA` |
| `SEMICOLON` |
| `PERIOD` |
| `SPACE` |
| `CUSTOM` |
| `AUTODETECT` |
## CommentActionType
| Value |
| --------------------------------- |
| `COMMENT_ACTION_TYPE_UNSPECIFIED` |
| `NO_COMMENT_ACTION_CHANGE` |
| `RESOLVE` |
| `REOPEN` |
## CommentThreadStatus
| Value |
| -------------------- |
| `STATUS_UNSPECIFIED` |
| `OPEN` |
| `RESOLVED` |
## HistogramChartSpecLegendPosition
| Value |
| --------------------------------------------- |
| `HISTOGRAM_CHART_LEGEND_POSITION_UNSPECIFIED` |
| `BOTTOM_LEGEND` |
| `LEFT_LEGEND` |
| `RIGHT_LEGEND` |
| `TOP_LEGEND` |
| `NO_LEGEND` |
| `INSIDE_LEGEND` |
## HorizontalAlign
| Value |
| ------------------------------ |
| `HORIZONTAL_ALIGN_UNSPECIFIED` |
| `LEFT` |
| `CENTER` |
| `RIGHT` |
## InterpolationPointType
| Value |
| -------------------------------------- |
| `INTERPOLATION_POINT_TYPE_UNSPECIFIED` |
| `MIN` |
| `MAX` |
| `NUMBER` |
| `PERCENT` |
| `PERCENTILE` |
## LineStyleType
| Value |
| ---------------------------- |
| `LINE_DASH_TYPE_UNSPECIFIED` |
| `INVISIBLE` |
| `CUSTOM` |
| `SOLID` |
| `DOTTED` |
| `MEDIUM_DASHED` |
| `MEDIUM_DASHED_DOTTED` |
| `LONG_DASHED` |
| `LONG_DASHED_DOTTED` |
## MergeType
| Value |
| --------------- |
| `MERGE_ALL` |
| `MERGE_COLUMNS` |
| `MERGE_ROWS` |
## NumberFormatType
| Value |
| -------------------------------- |
| `NUMBER_FORMAT_TYPE_UNSPECIFIED` |
| `TEXT` |
| `NUMBER` |
| `PERCENT` |
| `CURRENCY` |
| `DATE` |
| `TIME` |
| `DATE_TIME` |
| `SCIENTIFIC` |
## OrgChartSpecNodeSize
| Value |
| ---------------------------------- |
| `ORG_CHART_LABEL_SIZE_UNSPECIFIED` |
| `SMALL` |
| `MEDIUM` |
| `LARGE` |
## PasteOrientation
| Value |
| ----------- |
| `NORMAL` |
| `TRANSPOSE` |
## PasteType
| Value |
| ------------------------------ |
| `PASTE_NORMAL` |
| `PASTE_VALUES` |
| `PASTE_FORMAT` |
| `PASTE_NO_BORDERS` |
| `PASTE_FORMULA` |
| `PASTE_DATA_VALIDATION` |
| `PASTE_CONDITIONAL_FORMATTING` |
## PersonPropertiesDisplayFormat
| Value |
| ---------------------------- |
| `DISPLAY_FORMAT_UNSPECIFIED` |
| `DEFAULT` |
| `LAST_NAME_COMMA_FIRST_NAME` |
| `EMAIL` |
## PieChartSpecLegendPosition
| Value |
| --------------------------------------- |
| `PIE_CHART_LEGEND_POSITION_UNSPECIFIED` |
| `BOTTOM_LEGEND` |
| `LEFT_LEGEND` |
| `RIGHT_LEGEND` |
| `TOP_LEGEND` |
| `NO_LEGEND` |
| `LABELED_LEGEND` |
## PivotTableValueLayout
| Value |
| ------------ |
| `HORIZONTAL` |
| `VERTICAL` |
## PivotValueCalculatedDisplayType
| Value |
| ------------------------------------------------- |
| `PIVOT_VALUE_CALCULATED_DISPLAY_TYPE_UNSPECIFIED` |
| `PERCENT_OF_ROW_TOTAL` |
| `PERCENT_OF_COLUMN_TOTAL` |
| `PERCENT_OF_GRAND_TOTAL` |
## PivotValueSummarizeFunction
| Value |
| ------------------------------------------- |
| `PIVOT_STANDARD_VALUE_FUNCTION_UNSPECIFIED` |
| `SUM` |
| `COUNTA` |
| `COUNT` |
| `COUNTUNIQUE` |
| `AVERAGE` |
| `MAX` |
| `MIN` |
| `MEDIAN` |
| `PRODUCT` |
| `STDEV` |
| `STDEVP` |
| `VAR` |
| `VARP` |
| `CUSTOM` |
| `NONE` |
## PointStyleShape
| Value |
| ------------------------- |
| `POINT_SHAPE_UNSPECIFIED` |
| `CIRCLE` |
| `DIAMOND` |
| `HEXAGON` |
| `PENTAGON` |
| `SQUARE` |
| `STAR` |
| `TRIANGLE` |
| `X_MARK` |
## RecalculationInterval
| Value |
| ------------------------------------ |
| `RECALCULATION_INTERVAL_UNSPECIFIED` |
| `ON_CHANGE` |
| `MINUTE` |
| `HOUR` |
## ScorecardChartSpecAggregateType
| Value |
| ---------------------------------- |
| `CHART_AGGREGATE_TYPE_UNSPECIFIED` |
| `AVERAGE` |
| `COUNT` |
| `MAX` |
| `MEDIAN` |
| `MIN` |
| `SUM` |
## ScorecardChartSpecNumberFormatSource
| Value |
| -------------------------------------- |
| `CHART_NUMBER_FORMAT_SOURCE_UNDEFINED` |
| `FROM_DATA` |
| `CUSTOM` |
## SheetType
| Value |
| ------------------------ |
| `SHEET_TYPE_UNSPECIFIED` |
| `GRID` |
| `OBJECT` |
| `DATA_SOURCE` |
## SortOrder
| Value |
| ------------------------ |
| `SORT_ORDER_UNSPECIFIED` |
| `ASCENDING` |
| `DESCENDING` |
## TableColumnPropertiesColumnType
| Value |
| ------------------------- |
| `COLUMN_TYPE_UNSPECIFIED` |
| `DOUBLE` |
| `CURRENCY` |
| `PERCENT` |
| `DATE` |
| `TIME` |
| `DATE_TIME` |
| `TEXT` |
| `BOOLEAN` |
| `DROPDOWN` |
| `FILES_CHIP` |
| `PEOPLE_CHIP` |
| `FINANCE_CHIP` |
| `PLACE_CHIP` |
| `RATINGS_CHIP` |
## ThemeColorType
| Value |
| ------------------------------ |
| `THEME_COLOR_TYPE_UNSPECIFIED` |
| `TEXT` |
| `BACKGROUND` |
| `ACCENT1` |
| `ACCENT2` |
| `ACCENT3` |
| `ACCENT4` |
| `ACCENT5` |
| `ACCENT6` |
| `LINK` |
## VerticalAlign
| Value |
| ---------------------------- |
| `VERTICAL_ALIGN_UNSPECIFIED` |
| `TOP` |
| `MIDDLE` |
| `BOTTOM` |
## WaterfallChartSpecStackedType
| Value |
| ------------------------------------ |
| `WATERFALL_STACKED_TYPE_UNSPECIFIED` |
| `STACKED` |
| `SEQUENTIAL` |
## WrapStrategy
| Value |
| --------------------------- |
| `WRAP_STRATEGY_UNSPECIFIED` |
| `OVERFLOW_CELL` |
| `LEGACY_WRAP` |
| `CLIP` |
| `WRAP` |