שימוש במנהל התקן JDBC ל-BigQuery

מנהל ההתקן (driver) של Java Database Connectivity‏ (JDBC) ל-BigQuery מקשר את אפליקציות Java ל-BigQuery, ומאפשר לכם להשתמש בתכונות של BigQuery עם כלי התשתית המועדפים שלכם. כדי לחבר אפליקציות שאינן Java ל-BigQuery, משתמשים במנהל התקן של Open Database Connectivity‏ (ODBC) ל-BigQuery.

מגבלות

מגבלות השימוש בדרייבר JDBC ל-BigQuery:

• הדרייבר ספציפי ל-BigQuery ואי אפשר להשתמש בו עם מוצרים או שירותים אחרים.
• סוג הנתונים INTERVAL לא נתמך ב-BigQuery Storage Read API.
• חלות כל המגבלות של שפת טיפול בנתונים (DML).

לפני שמתחילים

1. חשוב לוודא שאתם מכירים את מנהלי ההתקנים של JDBC, את Apache Maven ואת חבילת java.sql.
2. מוודאים שהמערכת מוגדרת עם סביבת זמן ריצה של Java‏ (JRE) בגרסה 8.0 ואילך. מידע על בדיקת גרסת ה-JRE זמין במאמר אימות סביבת ה-JRE.

3. מאמתים את הזהות ב-BigQuery ורושמים את הפרטים הבאים, שבהם תשתמשו בהמשך כשתקימו חיבור עם מנהל ההתקן של JDBC ל-BigQuery. צריך לציין רק את המידע שמתאים לשיטת האימות שבה אתם משתמשים.

   שיטת אימות	פרטי אימות	דוגמה	מאפיין של חיבור (להגדרה בהמשך)
   חשבון שירות רגיל	כתובת האימייל של חשבון השירות	bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.com	OAuthServiceAcctEmail
   	מפתח של חשבון שירות (אובייקט JSON)	my-sa-key	OAuthPvtKey
   קובץ מפתח של חשבון שירות	קובץ המפתח של חשבון השירות (נתיב מלא)	path/to/file/secret.json	OAuthPvtKeyPath
   חשבון משתמש ב-Google	מזהה לקוח	123-abc.apps.googleusercontent.com	OAuthClientId
   	סוד לקוח	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   טוקן גישה שנוצר מראש	טוקן גישה	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   טוקן רענון שנוצר מראש	טוקן רענון	1/fFAGRNJru1FTz70BzhT3Zg	OAuthRefreshToken
   	מזהה לקוח	123-abc.apps.googleusercontent.com	OAuthClientId
   	סוד לקוח	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Application Default Credentials	ללא	לא רלוונטי	לא רלוונטי
   קובץ תצורה	קובץ תצורה (אובייקט JSON או נתיב מלא)	path/to/file/secret.json	OAuthPvtKey
   אובייקט הגדרת חשבון חיצוני	אובייקט של הגדרת חשבון	external_account_configuration_object	OAuthPvtKey
   אחר	מאפיין הקהל של קובץ ההגדרה של החשבון החיצוני	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	אחזור טוקנים וקובץ מידע על הסביבה	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	פרויקט של משתמש (רק אם משתמשים במאגר כוח עבודה)	my_project	BYOID_PoolUserProject
   	ה-URI להתחזות לחשבון שירות (רק אם משתמשים במאגר כוח אדם)	my-sa	BYOID_SA_Impersonation_Uri
   	אסימון Security Token Service שמבוסס על מפרט החלפת האסימונים	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	נקודת הקצה להחלפת טוקנים של Security Token Service	https://sts.googleapis.com/v1/token	BYOID_TokenUri

הגדרת סביבת הפיתוח

מנהל ההתקן של JDBC ל-BigQuery זמין ב-Maven Central.

כדי להגדיר את סביבת הפיתוח באמצעות מנהל ההתקן JDBC, מוסיפים את מנהל ההתקן כתלות לפרויקט:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>0.3.0</version>
</dependency>

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:0.3.0")
}

יצירת חיבור

כדי ליצור חיבור בין אפליקציית Java לבין BigQuery באמצעות מנהל התקן JDBC ל-BigQuery, צריך לבצע את הפעולות הבאות:

1. מזהים את מחרוזת החיבור של מנהל ההתקן של JDBC ל-BigQuery. המחרוזת הזו כוללת את כל המידע שנדרש כדי ליצור חיבור בין אפליקציית Java לבין BigQuery. מחרוזת החיבור היא בפורמט הבא:

   jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫HOST: כתובת ה-DNS או כתובת ה-IP של השרת.
   • ‫PORT: מספר יציאת ה-TCP.
   • ‫PROJECT_ID: מזהה הפרויקט ב-BigQuery.
   • ‫AUTH_TYPE: מספר שמציין את סוג האימות שבו השתמשתם. אחת מהאפשרויות הבאות:
     • ‫0: לאימות של חשבון שירות (סטנדרטי וקובץ מפתח)
     • ‫1: לאימות של חשבון משתמש ב-Google
     • ‫2: לאימות של אסימון רענון או אסימון גישה שנוצרו מראש
     • ‫3: לאימות של Application Default Credential
     • ‫4: לשיטות אימות אחרות
   • ‫AUTH_PROPS: פרטי האימות שרשמתם כשהזדהיתם ב-BigQuery, שמופיעים בפורמט property_1=value_1; property_2=value_2;... – לדוגמה, OAuthPvtKeyPath=path/to/file/secret.json, אם הזדהיתם באמצעות קובץ מפתח של חשבון שירות.
   • ‫OTHER_PROPS (אופציונלי): מאפייני חיבור נוספים למנהל התקן JDBC, שמופיעים בפורמט property_1=value_1; property_2=value_2;.... רשימה מלאה של מאפייני החיבור זמינה במאמר מאפייני חיבור.

2. מחברים את אפליקציית Java למנהל ההתקן של JDBC ל-BigQuery באמצעות המחלקה DriverManager או DataSource.

   • מתחברים לכיתה DriverManager:

     import java.sql.Connection;
     import java.sql.DriverManager;
     
     private static Connection getJdbcConnectionDM(){
       Connection connection = DriverManager.getConnection(CONNECTION_STRING);
       return connection;
     }

     מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

   • מתחברים לכיתה DataSource:

     import com.google.cloud.bigquery.jdbc.DataSource;
     import java.sql.Connection;
     import java.sql.SQLException;
     
     private static public Connection getJdbcConnectionDS() throws SQLException {
       Connection connection = null;
       DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
       dataSource.setURL(CONNECTION_STRING);
       connection = dataSource.getConnection();
       return connection;
     }

     מחליפים את CONNECTION_STRING במחרוזת החיבור מהשלב הקודם.

     במחלקה DataSource יש גם שיטות setter שאפשר להשתמש בהן כדי להגדיר מאפייני חיבור, במקום לכלול אותם במחרוזת החיבור. לדוגמה:

     private static Connection getConnection() throws SQLException {
       DataSource ds = new DataSource();
       ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
       ds.setAuthType(3);  // Application Default Credentials
       ds.setProjectId("MyTestProject");
       ds.setEnableHighThroughputAPI(true);
       ds.setLogLevel("6");
       ds.setUseQueryCache(false);
       return ds.getConnection();
     }

מאפייני החיבור

מאפייני החיבור של מנהל ההתקן JDBC הם פרמטרים של הגדרה שכוללים במחרוזת החיבור או מעבירים דרך שיטות setter כשמקימים חיבור למסד נתונים. מנהל ההתקן של JDBC עבור BigQuery תומך במאפייני החיבור הבאים.

הרצת שאילתות באמצעות הדרייבר

אחרי שהאפליקציה שלכם ב-Java מחוברת ל-BigQuery דרך מנהל ההתקן JDBC, אתם יכולים להריץ שאילתות בסביבת הפיתוח שלכם דרך תהליך JDBC רגיל. כל המכסות והמגבלות של BigQuery חלות.

מיפוי סוגי נתונים

כשמריצים שאילתות דרך מנהל ההתקן של JDBC ל-BigQuery, מתבצע מיפוי של סוגי הנתונים הבאים:

דוגמאות

בקטעים הבאים מופיעות דוגמאות לשימוש בתכונות של BigQuery באמצעות מנהל ההתקן JDBC ל-BigQuery.

פרמטרים תלויי מיקום

בדוגמה הבאה מריצים שאילתה עם פרמטר תלוי מיקום:

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

רשומות בתוך רשומות ורשומות חוזרות

בדוגמה הבאה מוצגת שאילתה של רשומת הבסיס של נתוני Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

הדרייבר מחזיר את רשומת הבסיס כאובייקט struct או כייצוג מחרוזת של אובייקט JSON. התוצאה אמורה להיראות כך:

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

בדוגמה הבאה מוצגת שאילתה לגבי רכיבי המשנה של אובייקט Struct:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

הדוגמה הבאה מציגה שאילתה של מערך רגיל של נתונים חוזרים, ואז בודקת את התוצאה:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

בדוגמה הבאה מבוצעת שאילתה על Struct מערך של נתונים חוזרים, ואז מתבצעת בדיקה של התוצאה:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

הוספה בכמות גדולה

בדוגמה הבאה מבוצעת פעולת הוספה בכמות גדולה באמצעות השיטה executeBatch.

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

רישום ביומן

כדי לפתור בעיות במנהל ההתקן של JDBC ל-BigQuery, אפשר להפעיל רישום ביומן על ידי הגדרת מאפייני חיבור או משתני סביבה. רישום ביומן יכול להשפיע על הביצועים ולתפוס מקום בדיסק, לכן מומלץ להפעיל אותו רק באופן זמני כדי לתעד בעיה.

רמות יומן

המאפיין LogLevel קובע את רמת הפירוט שמתועדת בחבילה java.util.logging:

• 0: OFF (ברירת מחדל)
• 1: SEVERE
• 2: ‏WARNING
• 3: ‏INFO
• 4: ‏CONFIG
• 5: ‏FINE
• 6: ‏FINER
• 7: ‏FINEST
• 8: ALL

אנחנו ממליצים על רמה 6 לפתרון בעיות כללי. רמות 7 ו-8 מוגבלות ל-ResultSet פעולות, ומייצרות נפח גדול של יומנים.

הפעלת רישום ביומן במחרוזת החיבור

כדי להפעיל את הרישום ביומן במחרוזת החיבור, מוסיפים את מאפייני החיבור LogLevel ו-LogPath, לדוגמה:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

הפעלת רישום ביומן באמצעות משתני סביבה

אם כלי הפיתוח לא מאפשר עריכה של מחרוזת החיבור, אפשר גם להגדיר את רמת היומן ונתיב היומן באמצעות משתני הסביבה הבאים לפני שמריצים את האפליקציה:

• ‫BIGQUERY_JDBC_LOG_LEVEL: הרמה ביומן (0-8).
• ‫BIGQUERY_JDBC_LOG_PATH: הספרייה של קובצי היומן.

לדוגמה, בסביבה של Linux או macOS, מריצים את הפקודה הבאה:

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

תמחור

אפשר להוריד את מנהל ההתקן JDBC ל-BigQuery ללא עלות. עם זאת, כשמשתמשים בדרייבר, חלים תעריפי BigQuery הרגילים.

המאמרים הבאים

• מידע נוסף על מנהל ההתקן של ODBC ל-BigQuery
• כדאי לעיין בכלים נוספים למפתחים של BigQuery.