Skip to content

Commit 3151e09

Browse files
garrettjonesgooglegarrettjonesgoogle
committed
Doc improvements
1 parent 8e26935 commit 3151e09

6 files changed

Lines changed: 73 additions & 14 deletions

File tree

‎google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/FieldValue.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,9 @@ public boolean getBooleanValue() {
195195
* Returns this field's value as a {@link Timestamp}. This method should only be used if the
196196
* corresponding field has {@link Field.Type#timestamp()} type.
197197
*
198+
* NOTE: Although {@link Timestamp} is capable of holding up to
199+
* nanosecond precision, BigQuery only supports up to microsecond precision.
200+
*
198201
* @throws ClassCastException if the field is not a primitive type
199202
* @throws NumberFormatException if the field's value could not be converted to a
200203
* {@link Timestamp}
@@ -221,6 +224,9 @@ public CivilDate getDateValue() {
221224
/**
222225
* Returns this field's value as a {@link CivilTime}. This method should only be used if the
223226
* corresponding field has {@link Field.Type#time()} type.
227+
*
228+
* NOTE: Although {@link CivilTime} is capable of holding up to
229+
* nanosecond precision, BigQuery only supports up to microsecond precision.
224230
*/
225231
public CivilTime getTimeValue() {
226232
return CivilTime.parseTime(getStringValue());

‎google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/QueryParameterValue.java‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -225,23 +225,31 @@ public static QueryParameterValue timestamp(Long valueMicroseconds) {
225225
}
226226

227227
/**
228-
* Creates a {@code QueryParameterValue} object with a type of TIMESTAMP. Must be in the format
229-
* "yyyy-MM-dd HH:mm:ss.SSSSSSZZ", e.g. "2014-08-19 12:41:35.220000+00:00".
228+
* Creates a {@code QueryParameterValue} object with a type of TIMESTAMP.
229+
* The string is validated against {@link Timestamp#parseCloudTimestamp}; see that function
230+
* for details on format.
231+
*
232+
* NOTE: Although {@link Timestamp} is capable of holding up to
233+
* nanosecond precision, BigQuery only supports up to microsecond precision.
230234
*/
231235
public static QueryParameterValue timestamp(String value) {
232236
return of(value, StandardSQLTypeName.TIMESTAMP);
233237
}
234238

235239
/**
236240
* Creates a {@code QueryParameterValue} object with a type of TIMESTAMP.
241+
*
242+
* NOTE: Although {@link Timestamp} is capable of holding up to
243+
* nanosecond precision, BigQuery only supports up to microsecond precision.
237244
*/
238245
public static QueryParameterValue timestamp(Timestamp value) {
239246
return of(value, StandardSQLTypeName.TIMESTAMP);
240247
}
241248

242249
/**
243-
* Creates a {@code QueryParameterValue} object with a type of DATE. Must be in the format
244-
* "yyyy-MM-dd", e.g. "2014-08-19".
250+
* Creates a {@code QueryParameterValue} object with a type of DATE.
251+
* The string is validated against {@link CivilDate#parseDate}; see that function
252+
* for details on format.
245253
*/
246254
public static QueryParameterValue date(String value) {
247255
return of(value, StandardSQLTypeName.DATE);
@@ -255,23 +263,31 @@ public static QueryParameterValue date(CivilDate value) {
255263
}
256264

257265
/**
258-
* Creates a {@code QueryParameterValue} object with a type of TIME. Must be in the format
259-
* "HH:mm:ss.SSSSSS", e.g. "12:41:35.220000".
266+
* Creates a {@code QueryParameterValue} object with a type of TIME.
267+
* The string is validated against {@link CivilTime#parseTime}; see that function
268+
* for details on format.
269+
*
270+
* NOTE: Although {@link CivilTime} is capable of holding up to
271+
* nanosecond precision, BigQuery only supports up to microsecond precision.
260272
*/
261273
public static QueryParameterValue time(String value) {
262274
return of(value, StandardSQLTypeName.TIME);
263275
}
264276

265277
/**
266278
* Creates a {@code QueryParameterValue} object with a type of TIME.
279+
*
280+
* NOTE: Although {@link CivilTime} is capable of holding up to
281+
* nanosecond precision, BigQuery only supports up to microsecond precision.
267282
*/
268283
public static QueryParameterValue time(CivilTime value) {
269284
return of(value, StandardSQLTypeName.TIME);
270285
}
271286

272287
/**
273288
* Creates a {@code QueryParameterValue} object with a type of DATETIME.
274-
* Must be in the format "yyyy-MM-dd HH:mm:ss.SSSSSS", e.g. "2014-08-19 12:41:35.220000".
289+
* The string is validated against {@link CivilDateTime#parseDateTime}; see that function
290+
* for details on format.
275291
*/
276292
public static QueryParameterValue dateTime(String value) {
277293
return of(value, StandardSQLTypeName.DATETIME);

‎google-cloud-core/src/main/java/com/google/cloud/CivilDate.java‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,11 @@ public static CivilDate ofYearMonthDay(int year, int month, int dayOfMonth) {
6363
return new CivilDate(year, month, dayOfMonth);
6464
}
6565

66-
/** @param date Date in RFC 3339 date format (yyyy-mm-dd). */
66+
/**
67+
* Creates a CivilDate instance from the given string.
68+
*
69+
* @param date Date in RFC 3339 date format (yyyy-mm-dd).
70+
*/
6771
public static CivilDate parseDate(String date) {
6872
Matcher matcher = FORMAT_REGEXP.matcher(date);
6973
if (!matcher.matches()) {

‎google-cloud-core/src/main/java/com/google/cloud/CivilDateTime.java‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
import java.util.regex.Pattern;
2323

2424
/**
25-
* Represents a date and time with no timezone, e.g. e.g. 2017-03-17 07:41:35.220000.
25+
* Represents a date and time with no timezone, e.g. 2017-03-17 07:41:35.220000.
2626
*
2727
* CivilDateTime holds values for BigQuery DATETIME
2828
* (https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#datetime-type).
@@ -64,8 +64,21 @@ public static CivilDateTime ofDateAndTime(CivilDate date, CivilTime time) {
6464
}
6565

6666
/**
67-
* @param dateTime Date plus time: (yyyy-MM-dd[ HH:mm:ss.SSSSSSSSS]) or
68-
* (yyyy-MM-dd['T'HH:mm:ss.SSSSSSSSS]).
67+
* Creates a CivilDateTime instance from the given string.
68+
*
69+
* @param dateTime Date plus time: (yyyy-MM-dd[ HH:mm:ss[.SSSSSSSSS]]) or
70+
* (yyyy-MM-dd['T'HH:mm:ss[.SSSSSSSSS]]). If present, the fractional second component can be
71+
* from 1 to 9 digits. Examples:
72+
*
73+
* <ul>
74+
* <li>2017-03-17</li>
75+
* <li>2017-03-17 07:41:35</li>
76+
* <li>2017-03-17 07:41:35.220</li>
77+
* <li>2017-03-17 07:41:35.220550900</li>
78+
* <li>2017-03-17T07:41:35</li>
79+
* <li>2017-03-17T07:41:35.220</li>
80+
* <li>2017-03-17T07:41:35.220550900</li>
81+
* </ul>
6982
*/
7083
public static CivilDateTime parseDateTime(String dateTime) {
7184
if (DATE_ONLY_PATTERN.matcher(dateTime).matches()) {

‎google-cloud-core/src/main/java/com/google/cloud/CivilTime.java‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,18 @@ public static CivilTime ofHoursMinutesSecondsNanos(int hours, int minutes, int s
5959
return new CivilTime(hours, minutes, seconds, nanos);
6060
}
6161

62-
/** @param time time in the format hh:mm:ss or hh:mm:ss.SSSSSSSSS */
62+
/**
63+
* Creates a CivilTime instance from the given string.
64+
*
65+
* @param time time in the format hh:mm:ss[.SSSSSSSSS]. If present, the fractional second
66+
* component can be from 1 to 9 digits. Examples:
67+
*
68+
* <ul>
69+
* <li>07:41:35</li>
70+
* <li>07:41:35.220</li>
71+
* <li>07:41:35.220550900</li>
72+
* </ul>
73+
*/
6374
public static CivilTime parseTime(String time) {
6475
Matcher matcher = FORMAT_REGEXP.matcher(time);
6576
if (!matcher.matches()) {

‎google-cloud-core/src/main/java/com/google/cloud/Timestamp.java‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818

1919
import static com.google.common.base.Preconditions.checkArgument;
2020

21-
import com.google.common.base.Preconditions;
2221
import com.google.common.base.Strings;
2322
import com.google.protobuf.util.Timestamps;
2423
import java.util.Objects;
@@ -180,7 +179,17 @@ public static Timestamp parseTimestamp(String timestamp) {
180179
/**
181180
* Creates a Timestamp instance from the given string. String is in the format
182181
* yyyy-MM-dd[ HH:mm:ss[.SSSSSSSSS]][time zone]. Here, time zone is in the form (+|-)HH:mm.
183-
* If no timezone is given, UTC is assumed.
182+
* If no timezone is given, UTC is assumed. Examples:
183+
*
184+
* <ul>
185+
* <li>2017-03-17</li>
186+
* <li>2017-03-17+02:00</li>
187+
* <li>2017-03-17 07:41:35</li>
188+
* <li>2017-03-17 07:41:35+02:00</li>
189+
* <li>2017-03-17 07:41:35.220</li>
190+
* <li>2017-03-17 07:41:35.220550900</li>
191+
* <li>2017-03-17 07:41:35.220550900+02:00</li>
192+
* </ul>
184193
*/
185194
public static Timestamp parseCloudTimestamp(String timestamp) {
186195
String date = null;

0 commit comments

Comments
 (0)