Summarize Table Data

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
type SummarizeTable = {
    filter?: FilterExpression;
    columns?: ColumnsProjection;
    summaries?: SummaryExpressionList;
    sort?: SortExpression;
    summariesFilter?: FilterExpression;
    /*
     * The consistency level for this request.
     *
     * @default strong
     */
    consistency?: "strong" | "eventual";
    page?: {
        /*
         * The number of records returned by summarize. If the amount of data you have exceeds this, or you have
         * more complex reporting requirements, we recommend that you use the aggregate endpoint instead.
         *
         * @default 20
         * @maximum 1000
         * @minimum 1
         */
        size?: number;
    };
};

/**
 * @minProperties 1
 */
type FilterExpression = {
    $exists?: string;
    $existsNot?: string;
    $any?: FilterList;
    $all?: FilterList;
    $none?: FilterList;
    $not?: FilterList;
} & {
    [key: string]: FilterColumn;
};

/**
 * @example name
 * @example email
 * @example created_at
 */
type ColumnsProjection = string[];

/**
 * The description of the summaries you wish to receive. Set each key to be the field name
 * you'd like for the summary. These names must not collide with other columns you've
 * requested from `columns`; including implicit requests like `settings.*`.
 * 
 * The value for each key needs to be an object. This object should contain one key and one 
 * value only. In this object, the key should be set to the summary function you wish to use
 * and the value set to the column name to be summarized.
 * 
 * The column being summarized cannot be an internal column (id, xata.*), nor the base of
 * an object, i.e. if `settings` is an object with `dark_mode` as a field, you may summarize
 * `settings.dark_mode` but not `settings` nor `settings.*`.
 * 
 * @example {"all_users":{"count":"*"},"total_created":{"count":"created_at"},"min_cost":{"min":"cost"},"max_happiness":{"max":"happiness"},"total_revenue":{"sum":"revenue"},"average_speed":{"average":"speed"}}
 */
type SummaryExpressionList = {
    [key: string]: SummaryExpression;
};

type SortExpression = string[] | {
    [key: string]: SortOrder;
} | {
    [key: string]: SortOrder;
}[];

type FilterList = FilterExpression | FilterExpression[];

type FilterColumn = FilterColumnIncludes | FilterPredicate | FilterList;

/**
 * A summary expression is the description of a single summary operation. It consists of a single
 * key representing the operation, and a value representing the column to be operated on.
 * 
 * The column being summarized cannot be an internal column (id, xata.*), nor the base of
 * an object, i.e. if `settings` is an object with `dark_mode` as a field, you may summarize
 * `settings.dark_mode` but not `settings` nor `settings.*`.
 * 
 * We currently support several aggregation functions. Not all functions can be run on all column
 * types.
 * 
 *   - `count` is used to count the number of records in each group. Use `{"count": "*"}` to count
 *     all columns present, otherwise `{"count": "<column_path>"}` to count the number of non-null
 *     values are present at column path.
 * 
 *     Count can be used on any column type, and always returns an int.
 * 
 *   - `min` calculates the minimum value in each group. `min` is compatible with most types;
 *     string, multiple, text, email, int, float, and datetime. It returns a value of the same
 *     type as operated on. This means that `{"lowest_latency": {"min": "latency"}}` where
 *     `latency` is an int, will always return an int.
 * 
 *   - `max` calculates the maximum value in each group. `max` shares the same compatibility as
 *     `min`.
 * 
 *   - `sum` adds up all values in a group. `sum` can be run on `int` and `float` types, and will
 *     return a value of the same type as requested.
 * 
 *   - `average` averages all values in a group. `average` can be run on `int` and `float` types, and
 *     always returns a float.
 * 
 * @example {"count":"deleted_at"}
 */
type SummaryExpression = Record<string, any>;

type SortOrder = "asc" | "desc" | "random";

/**
 * @maxProperties 1
 * @minProperties 1
 */
type FilterColumnIncludes = {
    $includes?: FilterPredicate;
    $includesAny?: FilterPredicate;
    $includesAll?: FilterPredicate;
    $includesNone?: FilterPredicate;
};

type FilterPredicate = FilterValue | FilterPredicate[] | FilterPredicateOp | FilterPredicateRangeOp;

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

type FilterValue = number | string | boolean;

/**
 * @maxProperties 1
 * @minProperties 1
 */
type FilterPredicateOp = {
    $any?: FilterPredicate[];
    $all?: FilterPredicate[];
    $none?: FilterPredicate | FilterPredicate[];
    $not?: FilterPredicate | FilterPredicate[];
    $is?: FilterValue | FilterValue[];
    $isNot?: FilterValue | FilterValue[];
    $lt?: FilterRangeValue;
    $le?: FilterRangeValue;
    $gt?: FilterRangeValue;
    $ge?: FilterRangeValue;
    $contains?: string;
    $startsWith?: string;
    $endsWith?: string;
    $pattern?: string;
};

/**
 * @maxProperties 2
 * @minProperties 2
 */
type FilterPredicateRangeOp = {
    $lt?: FilterRangeValue;
    $le?: FilterRangeValue;
    $gt?: FilterRangeValue;
    $ge?: FilterRangeValue;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

type FilterRangeValue = number | string;

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;