Skip to content

Commit 279755e

Browse files
niloc132niloc132
authored
Correct JS API docs and join type constants to match DHE (deephaven#5363)
Fixes deephaven#5348
1 parent 694bc0f commit 279755e

File tree

3 files changed

+115
-97
lines changed

3 files changed

+115
-97
lines changed

‎web/client-api/src/main/java/io/deephaven/web/client/api/JoinableTable.java

+92-6
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,14 @@
88
import io.deephaven.web.client.state.ClientTableState;
99
import jsinterop.annotations.JsIgnore;
1010
import jsinterop.annotations.JsMethod;
11+
import jsinterop.annotations.JsNullable;
1112
import jsinterop.annotations.JsOptional;
1213
import jsinterop.annotations.JsType;
1314

15+
/**
16+
* Represents a table which can be joined to another table. Current implementations are {@link JsTable} and
17+
* {@link JsTotalsTable}.
18+
*/
1419
@JsType(namespace = "dh")
1520
public interface JoinableTable {
1621
@JsIgnore
@@ -23,24 +28,105 @@ public interface JoinableTable {
2328
Promise<JsTable> snapshot(JsTable baseTable, @JsOptional Boolean doInitialSnapshot,
2429
@JsOptional String[] stampColumns);
2530

31+
/**
32+
* Joins this table to the provided table, using one of the specified join types:
33+
* <ul>
34+
* <li><code>AJ</code>, <code>ReverseAJ</code> (or <code>RAJ</code>) - inexact timeseries joins, based on the
35+
* provided matching rule.</li>
36+
* <li><code>CROSS_JOIN</code> (or <code>Join</code>) - cross join of all rows that have matching values in both
37+
* tables.</li>
38+
* <li><code>EXACT_JOIN</code> (or <code>ExactJoin</code> - matches values in exactly one row in the right table,
39+
* with errors if there is not exactly one.</li>
40+
* <li><code>NATURAL_JOIN</code> (or <code>Natural</code> - matches values in at most one row in the right table,
41+
* with nulls if there is no match or errors if there are multiple matches.</li>
42+
* </ul>
43+
*
44+
* Note that <code>Left</code> join is not supported here, unlike DHE.
45+
* <p>
46+
* See the <a href="https://deephaven.io/core/docs/conceptual/choose-joins/">Choose a join method</a> document for
47+
* more guidance on picking a join operation.
48+
*
49+
* @deprecated Instead, call the specific method for the join type.
50+
* @param joinType The type of join to perform, see the list above.
51+
* @param rightTable The table to match to values in this table
52+
* @param columnsToMatch Columns that should match
53+
* @param columnsToAdd Columns from the right table to add to the result - empty/null/absent to add all columns
54+
* @param asOfMatchRule If joinType is AJ/RAJ/ReverseAJ, the match rule to use
55+
* @return a promise that will resolve to the joined table
56+
*/
2657
@JsMethod
2758
@Deprecated
28-
Promise<JsTable> join(Object joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
29-
@JsOptional JsArray<String> columnsToAdd, @JsOptional Object asOfMatchRule);
59+
Promise<JsTable> join(String joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
60+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable String asOfMatchRule);
3061

62+
/**
63+
* Performs an inexact timeseries join, where rows in this table will have columns added from the closest matching
64+
* row from the right table.
65+
* <p>
66+
* The {@code asOfMatchRule} value can be one of:
67+
* <ul>
68+
* <li>LESS_THAN_EQUAL</li>
69+
* <li>LESS_THAN</li>
70+
* <li>GREATER_THAN_EQUAL</li>
71+
* <li>GREATER_THAN</li>
72+
* </ul>
73+
*
74+
* @param rightTable the table to match to values in this table
75+
* @param columnsToMatch the columns that should match, according to the asOfMatchRole
76+
* @param columnsToAdd columns from the right table to add to the resulting table, empty/null/absent to add all
77+
* columns
78+
* @param asOfMatchRule the match rule to use, see above
79+
* @return a promise that will resolve to the joined table
80+
*/
3181
@JsMethod
3282
Promise<JsTable> asOfJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
33-
@JsOptional JsArray<String> columnsToAdd, @JsOptional String asOfMatchRule);
83+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable String asOfMatchRule);
3484

85+
/**
86+
* a promise that will be resolved with the newly created table holding the results of the specified cross join
87+
* operation. The <b>columnsToAdd</b> parameter is optional, not specifying it will result in all columns from the
88+
* right table being added to the output. The <b>reserveBits</b> optional parameter lets the client control how the
89+
* key space is distributed between the rows in the two tables, see the Java <b>Table</b> class for details.
90+
*
91+
* @param rightTable the table to match to values in this table
92+
* @param columnsToMatch the columns that should match exactly
93+
* @param columnsToAdd columns from the right table to add to the resulting table, empty/null/absent to add all
94+
* columns
95+
* @param reserveBits the number of bits of key-space to initially reserve per group, null/absent will let the
96+
* server select a value
97+
* @return a promise that will resolve to the joined table
98+
*/
3599
@JsMethod
36100
Promise<JsTable> crossJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
37-
@JsOptional JsArray<String> columnsToAdd, @JsOptional Double reserve_bits);
101+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable Double reserveBits);
38102

103+
/**
104+
* a promise that will be resolved with the newly created table holding the results of the specified exact join
105+
* operation. The `columnsToAdd` parameter is optional, not specifying it will result in all columns from the right
106+
* table being added to the output.
107+
*
108+
* @param rightTable the table to match to values in this table
109+
* @param columnsToMatch the columns that should match exactly
110+
* @param columnsToAdd columns from the right table to add to the resulting table, empty/null/absent to add all
111+
* columns
112+
* @return a promise that will resolve to the joined table
113+
*/
39114
@JsMethod
40115
Promise<JsTable> exactJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
41-
@JsOptional JsArray<String> columnsToAdd);
116+
@JsOptional @JsNullable JsArray<String> columnsToAdd);
42117

118+
/**
119+
* a promise that will be resolved with the newly created table holding the results of the specified natural join
120+
* operation. The <b>columnsToAdd</b> parameter is optional, not specifying it will result in all columns from the
121+
* right table being added to the output.
122+
*
123+
* @param rightTable the table to match to values in this table
124+
* @param columnsToMatch the columns that should match exactly
125+
* @param columnsToAdd columns from the right table to add to the resulting table, empty/null/absent to add all
126+
* columns
127+
* @return a promise that will resolve to the joined table
128+
*/
43129
@JsMethod
44130
Promise<JsTable> naturalJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
45-
@JsOptional JsArray<String> columnsToAdd);
131+
@JsOptional @JsNullable JsArray<String> columnsToAdd);
46132
}

‎web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java

+13-81
Original file line numberDiff line numberDiff line change
@@ -1200,61 +1200,28 @@ public Promise<JsTable> snapshot(JsTable baseTable, @JsOptional Boolean doInitia
12001200
.then(state -> Promise.resolve(new JsTable(workerConnection, state)));
12011201
}
12021202

1203+
// inheritDoc lets us implement the inherited method, but still keep docs for TS
12031204
/**
1204-
* @deprecated a promise that will be resolved with a newly created table holding the results of the join operation.
1205-
* The last parameter is optional, and if not specified or empty, all columns from the right table will
1206-
* be added to the output. Callers are responsible for ensuring that there are no duplicates - a match
1207-
* pair can be passed instead of a name to specify the new name for the column. Supported `joinType`
1208-
* values (consult Deephaven's "Joining Data from Multiple Tables for more detail): "Join" <a href=
1209-
* 'https://docs.deephaven.io/latest/Content/writeQueries/tableOperations/joins.htm#Joining_Data_from_Multiple_Tables'>Joining_Data_from_Multiple_Tables</a>
1210-
* "Natural" "AJ" "ReverseAJ" "ExactJoin" "LeftJoin"
1211-
* @param joinType
1212-
* @param rightTable
1213-
* @param columnsToMatch
1214-
* @param columnsToAdd
1215-
* @param asOfMatchRule
1216-
* @return Promise of dh.Table
1205+
* @inheritDoc
12171206
*/
12181207
@Override
12191208
@JsMethod
12201209
@Deprecated
1221-
public Promise<JsTable> join(Object joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
1222-
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable Object asOfMatchRule) {
1223-
if (joinType.equals("AJ") || joinType.equals("RAJ")) {
1224-
return asOfJoin(rightTable, columnsToMatch, columnsToAdd, (String) asOfMatchRule);
1225-
} else if (joinType.equals("CROSS_JOIN")) {
1210+
public Promise<JsTable> join(String joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
1211+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable String asOfMatchRule) {
1212+
if (joinType.equals("AJ") || joinType.equals("RAJ") || joinType.equals("ReverseAJ")) {
1213+
return asOfJoin(rightTable, columnsToMatch, columnsToAdd, asOfMatchRule);
1214+
} else if (joinType.equals("CROSS_JOIN") || joinType.equals("Join")) {
12261215
return crossJoin(rightTable, columnsToMatch, columnsToAdd, null);
1227-
} else if (joinType.equals("EXACT_JOIN")) {
1216+
} else if (joinType.equals("EXACT_JOIN") || joinType.equals("ExactJoin")) {
12281217
return exactJoin(rightTable, columnsToMatch, columnsToAdd);
1229-
} else if (joinType.equals("NATURAL_JOIN")) {
1218+
} else if (joinType.equals("NATURAL_JOIN") || joinType.equals("Natural")) {
12301219
return naturalJoin(rightTable, columnsToMatch, columnsToAdd);
12311220
} else {
12321221
throw new IllegalArgumentException("Unsupported join type " + joinType);
12331222
}
12341223
}
12351224

1236-
/**
1237-
* a promise that will be resolved with the newly created table holding the results of the specified as-of join
1238-
* operation. The <b>columnsToAdd</b> parameter is optional, not specifying it will result in all columns from the
1239-
* right table being added to the output. The <b>asOfMatchRule</b> is optional, defaults to <b>LESS_THAN_EQUAL</b>
1240-
*
1241-
* <p>
1242-
* the allowed values are:
1243-
* </p>
1244-
*
1245-
* <ul>
1246-
* <li>LESS_THAN_EQUAL</li>
1247-
* <li>LESS_THAN</li>
1248-
* <li>GREATER_THAN_EQUAL</li>
1249-
* <li>GREATER_THAN</li>
1250-
* </ul>
1251-
*
1252-
* @param rightTable
1253-
* @param columnsToMatch
1254-
* @param columnsToAdd
1255-
* @param asOfMatchRule
1256-
* @return Promise og dh.Table
1257-
*/
12581225
@Override
12591226
@JsMethod
12601227
public Promise<JsTable> asOfJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
@@ -1280,23 +1247,10 @@ public Promise<JsTable> asOfJoin(JoinableTable rightTable, JsArray<String> colum
12801247
.then(state -> Promise.resolve(new JsTable(workerConnection, state)));
12811248
}
12821249

1283-
/**
1284-
* a promise that will be resolved with the newly created table holding the results of the specified cross join
1285-
* operation. The <b>columnsToAdd</b> parameter is optional, not specifying it will result in all columns from the
1286-
* right table being added to the output. The <b>reserveBits</b> optional parameter lets the client control how the
1287-
* key space is distributed between the rows in the two tables, see the Java <b>Table</b> class for details.
1288-
*
1289-
* @param rightTable
1290-
* @param columnsToMatch
1291-
* @param columnsToAdd
1292-
* @param reserve_bits
1293-
*
1294-
* @return Promise of dh.Table
1295-
*/
12961250
@Override
12971251
@JsMethod
12981252
public Promise<JsTable> crossJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
1299-
@JsOptional JsArray<String> columnsToAdd, @JsOptional Double reserve_bits) {
1253+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable Double reserveBits) {
13001254
if (rightTable.state().getConnection() != workerConnection) {
13011255
throw new IllegalStateException(
13021256
"Table argument passed to join is not from the same worker as current table");
@@ -1308,26 +1262,15 @@ public Promise<JsTable> crossJoin(JoinableTable rightTable, JsArray<String> colu
13081262
request.setResultId(state.getHandle().makeTicket());
13091263
request.setColumnsToMatchList(columnsToMatch);
13101264
request.setColumnsToAddList(columnsToAdd);
1311-
if (reserve_bits != null) {
1312-
request.setReserveBits(reserve_bits);
1265+
if (reserveBits != null) {
1266+
request.setReserveBits(reserveBits);
13131267
}
13141268
workerConnection.tableServiceClient().crossJoinTables(request, metadata, c::apply);
1315-
}, "join(" + rightTable + ", " + columnsToMatch + ", " + columnsToAdd + "," + reserve_bits + ")")
1269+
}, "join(" + rightTable + ", " + columnsToMatch + ", " + columnsToAdd + "," + reserveBits + ")")
13161270
.refetch(this, workerConnection.metadata())
13171271
.then(state -> Promise.resolve(new JsTable(workerConnection, state)));
13181272
}
13191273

1320-
/**
1321-
* a promise that will be resolved with the newly created table holding the results of the specified exact join
1322-
* operation. The `columnsToAdd` parameter is optional, not specifying it will result in all columns from the right
1323-
* table being added to the output.
1324-
*
1325-
* @param rightTable
1326-
* @param columnsToMatch
1327-
* @param columnsToAdd
1328-
*
1329-
* @return Promise of dh.Table
1330-
*/
13311274
@Override
13321275
@JsMethod
13331276
public Promise<JsTable> exactJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
@@ -1349,17 +1292,6 @@ public Promise<JsTable> exactJoin(JoinableTable rightTable, JsArray<String> colu
13491292
.then(state -> Promise.resolve(new JsTable(workerConnection, state)));
13501293
}
13511294

1352-
/**
1353-
* a promise that will be resolved with the newly created table holding the results of the specified natural join
1354-
* operation. The <b>columnsToAdd</b> parameter is optional, not specifying it will result in all columns from the
1355-
* right table being added to the output.
1356-
*
1357-
* @param rightTable
1358-
* @param columnsToMatch
1359-
* @param columnsToAdd
1360-
*
1361-
* @return Promise of dh.Table
1362-
*/
13631295
@Override
13641296
@JsMethod
13651297
public Promise<JsTable> naturalJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,

‎web/client-api/src/main/java/io/deephaven/web/client/api/JsTotalsTable.java

+10-10
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
import io.deephaven.web.shared.fu.RemoverFn;
1818
import jsinterop.annotations.JsIgnore;
1919
import jsinterop.annotations.JsMethod;
20+
import jsinterop.annotations.JsNullable;
2021
import jsinterop.annotations.JsOptional;
2122
import jsinterop.annotations.JsProperty;
2223
import jsinterop.base.Js;
@@ -318,44 +319,43 @@ public Promise<JsTable> freeze() {
318319

319320
@Override
320321
@JsMethod
321-
public Promise<JsTable> snapshot(JsTable baseTable, @JsOptional Boolean doInitialSnapshot,
322-
@JsOptional String[] stampColumns) {
322+
public Promise<JsTable> snapshot(JsTable baseTable, @JsOptional @JsNullable Boolean doInitialSnapshot,
323+
@JsOptional @JsNullable String[] stampColumns) {
323324
return wrappedTable.snapshot(baseTable, doInitialSnapshot, stampColumns);
324325
}
325326

326327
@Override
327-
@Deprecated
328328
@JsMethod
329-
public Promise<JsTable> join(Object joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
330-
@JsOptional JsArray<String> columnsToAdd, @JsOptional Object asOfMatchRule) {
329+
public Promise<JsTable> join(String joinType, JoinableTable rightTable, JsArray<String> columnsToMatch,
330+
@JsOptional JsArray<String> columnsToAdd, @JsOptional String asOfMatchRule) {
331331
return wrappedTable.join(joinType, rightTable, columnsToMatch, columnsToAdd, asOfMatchRule);
332332
}
333333

334334
@Override
335335
@JsMethod
336336
public Promise<JsTable> asOfJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
337-
@JsOptional JsArray<String> columnsToAdd, @JsOptional String asOfMatchRule) {
337+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable String asOfMatchRule) {
338338
return wrappedTable.asOfJoin(rightTable, columnsToMatch, columnsToAdd, asOfMatchRule);
339339
}
340340

341341
@Override
342342
@JsMethod
343343
public Promise<JsTable> crossJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
344-
@JsOptional JsArray<String> columnsToAdd, @JsOptional Double reserve_bits) {
345-
return wrappedTable.crossJoin(rightTable, columnsToMatch, columnsToAdd, reserve_bits);
344+
@JsOptional @JsNullable JsArray<String> columnsToAdd, @JsOptional @JsNullable Double reserveBits) {
345+
return wrappedTable.crossJoin(rightTable, columnsToMatch, columnsToAdd, reserveBits);
346346
}
347347

348348
@Override
349349
@JsMethod
350350
public Promise<JsTable> exactJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
351-
@JsOptional JsArray<String> columnsToAdd) {
351+
@JsOptional @JsNullable JsArray<String> columnsToAdd) {
352352
return wrappedTable.exactJoin(rightTable, columnsToMatch, columnsToAdd);
353353
}
354354

355355
@Override
356356
@JsMethod
357357
public Promise<JsTable> naturalJoin(JoinableTable rightTable, JsArray<String> columnsToMatch,
358-
@JsOptional JsArray<String> columnsToAdd) {
358+
@JsOptional @JsNullable JsArray<String> columnsToAdd) {
359359
return wrappedTable.naturalJoin(rightTable, columnsToMatch, columnsToAdd);
360360
}
361361
}

0 commit comments

Comments
 (0)