יצירה וניהול של נקודות פיצול

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

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

כדי לקבל את ההרשאה שנדרשת ליצירה ולניהול של נקודות פיצול, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד אדמין של מסד נתונים ב-Cloud Spanner (roles/spanner.databaseAdmin) במופע. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד שמוגדר מראש מכיל את ההרשאה spanner.databases.addSplitPoints, שנדרשת כדי ליצור ולנהל נקודות פיצול.
יכול להיות שתוכלו לקבל את ההרשאה הזו גם בתפקידים בהתאמה אישית או בתפקידים אחרים שמוגדרים מראש.
הדוגמאות ל-CLI של gcloud שבדף הזה מבוססות על ההנחות הבאות:
- הגדרתם את ה-CLI של gcloud לשימוש עם Spanner. אם אתם חדשים בשימוש ב-CLI של gcloud עם Spanner, כדאי לעיין במאמר יצירה של מסד נתונים וביצוע שאילתות בו באמצעות ה-CLI של gcloud.
- הגדרתם את ה-CLI של gcloud עם הפרויקט. לדוגמה:
```
gcloud config set core/project PROJECT_ID
```
מוודאים שיש מספיק צמתים במופע Spanner כדי לתמוך בעלייה הצפויה בתנועה. מידע נוסף מופיע במאמר סקירה כללית על פיצול מראש.

יצירת נקודות פיצול

אפשר ליצור נקודות פיצול באמצעות Google Cloud CLI או ממשקי ה-API ל-REST.

gcloud

אם רוצים ליצור נקודות פיצול באמצעות ה-CLI של gcloud, צריך ליצור קובץ שמכיל את כל הפיצולים ולספק את הנתיב בפקודת ה-CLI של gcloud. הקובץ לא יכול לחרוג ממגבלת ה-API של 100 נקודות לכל בקשת API. מידע נוסף זמין במאמר מכסות ומגבלות.

כדי לציין את נקודות הפיצול, צריך להשתמש בפורמט הבא בקובץ:

  ObjectType ObjectName (SplitValue1)
  ObjectType ObjectName (SplitValue2)
  ObjectType ObjectName (SplitValueN)

כשיוצרים את הקובץ, מחליפים את המשתנים הבאים:

‫ObjectType: סוג האובייקט שרוצים להוסיף לו פיצולים. הערכים התקינים הם TABLE ו-INDEX.
‫ObjectName: השם של טבלת מסד הנתונים או האינדקס.
‫SplitValue1..N: ערכי נקודות הפיצול שבהם רוצים להציג את הפיצולים.

כשיוצרים את הערכים של נקודות הפיצול בקובץ, צריך לפעול לפי הכללים הבאים:

ערכי מחרוזות צריכים להיות במירכאות בודדות. לדוגמה, 'splitKeyPart'
הערכים הבוליאניים צריכים להיות true או false.
ערכים מסוג נתונים של Spanner‏ INT64 ו-NUMERIC צריכים להיות במירכאות בודדות. לדוגמה, '123' או '99.99'.
כל שאר הערכים המספריים צריכים להיכתב בלי גרשיים בודדים. לדוגמה, 1.287.
ערכים של חותמת זמן צריכים להיות בפורמט '2020-06-18T17:24:53Z' בגרשיים בודדים.
צריך להוסיף סוגריים מסביב לערכים המפוצלים.
הסדר של ערכי המפתחות המפוצלים צריך להיות זהה לסדר של המפתח הראשי.
אם הערך המפוצל צריך לכלול פסיק, צריך להוסיף לפני הפסיק את התו `\`.
כדי לפצל אינדקסים, אפשר לספק את מפתח האינדקס או את האינדקס כולו ואת מפתח הטבלה המלא.
כשמציינים את נקודת הפיצול, תמיד צריך להשתמש במפתח המלא.

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

  TABLE Singers ('c32ca57a-786c-2268-09d4-95182a9930be')
  TABLE Singers ('bb98c7e2-8240-b780-346d-c5d63886594a')
  INDEX Order ('5b8bac71-0cb2-95e9-e1b0-89a027525460')
  TABLE Payment ('6cf41f21-2d77-318f-c504-816f0068db8b')
  INDEX Indx_A (2152120141932780000)
  TABLE TableD  (0,'7ef9d̦b22-d0e5-6041-8937-4bc6a7ef9db2')
  INDEX IndexXYZ ('8762203435012030000',NULL,NULL)
  INDEX IndexABC  (0, '2020-06-18T17:24:53Z', '2020-06-18T17:24:53Z') TableKey
  (123,'ab\,c')

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫SPLITS_FILE: הנתיב לקובץ הפיצולים.
‫INSTANCE_ID: מזהה המכונה.
‫DATABASE_ID: מזהה מסד הנתונים.
‫EXPIRATION_DATE: (אופציונלי) תאריך התפוגה של הנקודות המפוצלות. מקבלת חותמת זמן בפורמט '2020-06-18T17:24:53Z'.
‫INITIATOR: (אופציונלי) הגורם שיזם את נקודות הפיצול.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud spanner databases splits add DATABASE_ID \
--splits-file=SPLITS_FILE \
--instance=INSTANCE_ID \
--split-expiration-date=EXPIRATION_DATE \
--initiator=INITIATOR

‏Windows (PowerShell)

gcloud spanner databases splits add DATABASE_ID `
--splits-file=SPLITS_FILE `
--instance=INSTANCE_ID `
--split-expiration-date=EXPIRATION_DATE `
--initiator=INITIATOR

Windows‏ (cmd.exe)

gcloud spanner databases splits add DATABASE_ID ^
--splits-file=SPLITS_FILE ^
--instance=INSTANCE_ID ^
--split-expiration-date=EXPIRATION_DATE ^
--initiator=INITIATOR

REST v1

אפשר להשתמש ב-method‏ projects.instances.databases.addSplitPoints כדי ליצור נקודות פיצול.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט.
‫INSTANCE_ID: מזהה המכונה.
‫DATABASE_ID: מזהה מסד הנתונים.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints

תוכן בקשת JSON:

{
  "split_points": [
    {
      "table": "T1",
      "index": "T1_IDX",
      "expire_time": "2023-04-22T10:00:20.021Z",
      "keys": [
        {
          "key_parts": {
            "values": [
              3
            ]
          }
        },
        {
          "key_parts": {
            "values": [
              10
            ]
          }
        }
      ]
    },
    {
      "table": "T2",
      "expire_time": "2023-04-22T10:00:20.021Z",
      "keys": [
        {
          "key_parts": {
            "values": [
              50
            ]
          }
        }
      ]
    }
  ]
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints" | Select-Object -Expand Content

אמור להתקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

ספריות לקוח

Go


import (
	"context"
	"fmt"
	"io"
	"time"

	database "cloud.google.com/go/spanner/admin/database/apiv1"
	"cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
	adminpb "cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
	"google.golang.org/protobuf/types/known/structpb"
	"google.golang.org/protobuf/types/known/timestamppb"
)

// Adds split points to table and index
// AddSplitPoins API - https://pkg.go.dev/cloud.google.com/go/spanner/admin/database/apiv1#DatabaseAdminClient.AddSplitPoints
func addSplitpoints(w io.Writer, dbName string) error {
	ctx := context.Background()

	dbAdminClient, err := database.NewDatabaseAdminClient(ctx)
	if err != nil {
		return err
	}
	defer dbAdminClient.Close()

	// Database is assumed to exist - https://cloud.google.com/spanner/docs/getting-started/go#create_a_database
	// Singers table is assumed to be present
	ddl := []string{
		"CREATE INDEX IF NOT EXISTS SingersByFirstLastName ON Singers(FirstName, LastName)",
	}
	op, err := dbAdminClient.UpdateDatabaseDdl(ctx, &adminpb.UpdateDatabaseDdlRequest{
		Database:   dbName,
		Statements: ddl,
	})

	if err != nil {
		return fmt.Errorf("addSplitPoints: waiting for UpdateDatabaseDdlRequest failed: %w", err)
	}

	// Wait for the UpdateDatabaseDdl operation to finish.
	if err := op.Wait(ctx); err != nil {
		return fmt.Errorf("addSplitPoints: waiting for UpdateDatabaseDdlRequest to finish failed: %w", err)
	}
	fmt.Fprintf(w, "Added indexes for Split testing\n")

	splitTableKey := databasepb.SplitPoints_Key{
		KeyParts: &structpb.ListValue{
			Values: []*structpb.Value{
				structpb.NewStringValue("42"),
			},
		},
	}

	splitForTable := databasepb.SplitPoints{
		Table: "Singers",
		Keys:  []*databasepb.SplitPoints_Key{&splitTableKey},
	}

	splitIndexKey := databasepb.SplitPoints_Key{
		KeyParts: &structpb.ListValue{
			Values: []*structpb.Value{
				structpb.NewStringValue("John"),
				structpb.NewStringValue("Doe"),
			},
		},
	}

	splitForindex := databasepb.SplitPoints{
		Index: "SingersByFirstLastName",
		Keys:  []*databasepb.SplitPoints_Key{&splitIndexKey},
	}

	splitIndexKeyWithTableKeyPart := databasepb.SplitPoints_Key{
		KeyParts: &structpb.ListValue{
			Values: []*structpb.Value{
				structpb.NewStringValue("38"),
			},
		},
	}

	splitIndexKeyWithIndexKeyPart := databasepb.SplitPoints_Key{
		KeyParts: &structpb.ListValue{
			Values: []*structpb.Value{
				structpb.NewStringValue("Jane"),
				structpb.NewStringValue("Doe"),
			},
		},
	}

	// the index key part is first and table keypart is second in the split definition
	splitForindexWithTableKey := databasepb.SplitPoints{
		Index: "SingersByFirstLastName",
		Keys:  []*databasepb.SplitPoints_Key{&splitIndexKeyWithIndexKeyPart, &splitIndexKeyWithTableKeyPart},
	}

	splitTableKeyWithExpire := databasepb.SplitPoints_Key{
		KeyParts: &structpb.ListValue{
			Values: []*structpb.Value{
				structpb.NewStringValue("30"),
			},
		},
	}

	splitForTableWithExpire := databasepb.SplitPoints{
		Table: "Singers",
		Keys:  []*databasepb.SplitPoints_Key{&splitTableKeyWithExpire},
		// A timestamp in the past means immediate expiration.
		// The maximum value can be 30 days in the future.
		// Defaults to 10 days in the future if not specified.
		//
		// Setting the expiration time to next day
		ExpireTime: timestamppb.New(time.Now().Add(24 * time.Hour)),
	}

	// Add split points to table and index
	req := databasepb.AddSplitPointsRequest{
		Database:    dbName,
		SplitPoints: []*databasepb.SplitPoints{&splitForTable, &splitForindex, &splitForindexWithTableKey, &splitForTableWithExpire},
	}

	res, err := dbAdminClient.AddSplitPoints(ctx, &req)
	if err != nil {
		return fmt.Errorf("addSplitpoints: failed to add split points: %w", err)
	}

	fmt.Fprintf(w, "Added split points %s", res)
	return nil
}

Java


import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.spanner.admin.database.v1.DatabaseName;
import com.google.spanner.admin.database.v1.SplitPoints;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DatabaseAddSplitPointsSample {

  /***
   * Assume DDL for the underlying database:
   * <pre>{@code
   * CREATE TABLE Singers (
   * SingerId INT64 NOT NULL,
   * FirstName STRING(1024),
   * LastName STRING(1024),
   *  SingerInfo BYTES(MAX),
   * ) PRIMARY KEY(SingerId);
   *
   *
   * CREATE INDEX SingersByFirstLastName ON Singers(FirstName, LastName);
   * }</pre>
   */

  static void addSplitPoints() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    String databaseId = "my-database";
    addSplitPoints(projectId, instanceId, databaseId);
  }

  static void addSplitPoints(String projectId, String instanceId, String databaseId)
      throws IOException {
    try (Spanner spanner =
            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
      List<com.google.spanner.admin.database.v1.SplitPoints> splitPoints = new ArrayList<>();

      // table key
      com.google.spanner.admin.database.v1.SplitPoints splitPointForTable =
          SplitPoints.newBuilder()
              .setTable("Singers")
              .addKeys(
                  com.google.spanner.admin.database.v1.SplitPoints.Key.newBuilder()
                      .setKeyParts(
                          ListValue.newBuilder()
                              .addValues(Value.newBuilder().setStringValue("42").build())
                              .build()))
              .build();

      // index key without table key part
      com.google.spanner.admin.database.v1.SplitPoints splitPointForIndex =
          SplitPoints.newBuilder()
              .setIndex("SingersByFirstLastName")
              .addKeys(
                  com.google.spanner.admin.database.v1.SplitPoints.Key.newBuilder()
                      .setKeyParts(
                          ListValue.newBuilder()
                              .addValues(Value.newBuilder().setStringValue("John").build())
                              .addValues(Value.newBuilder().setStringValue("Doe").build())
                              .build()))
              .build();

      // index key with table key part, first key is the index key and second is the table key
      com.google.spanner.admin.database.v1.SplitPoints splitPointForIndexWitTableKey =
          SplitPoints.newBuilder()
              .setIndex("SingersByFirstLastName")
              .addKeys(
                  com.google.spanner.admin.database.v1.SplitPoints.Key.newBuilder()
                      .setKeyParts(
                          ListValue.newBuilder()
                              .addValues(Value.newBuilder().setStringValue("Jane").build())
                              .addValues(Value.newBuilder().setStringValue("Doe").build())
                              .build()))
              .addKeys(
                  com.google.spanner.admin.database.v1.SplitPoints.Key.newBuilder()
                      .setKeyParts(
                          ListValue.newBuilder()
                              .addValues(Value.newBuilder().setStringValue("38").build())
                              .build()))
              .build();

      splitPoints.add(splitPointForTable);
      splitPoints.add(splitPointForIndex);
      splitPoints.add(splitPointForIndexWitTableKey);
      databaseAdminClient.addSplitPoints(
          DatabaseName.of(projectId, instanceId, databaseId), splitPoints);

    } catch (Exception e) {
      // If the operation failed during execution, expose the cause.
      throw (SpannerException) e.getCause();
    }
  }
}

Node.js

// Import the Google Cloud client library for Spanner.
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance-id';
// const databaseId = 'my-database-id';

// Create a Spanner database admin client.
const spanner = new Spanner({projectId});
const databaseAdminClient = spanner.getDatabaseAdminClient();

try {
  // Add split points to table and index
  // first is a table level split that takes table primary key value
  // second is index level split with index key parts
  // third is index level split having index key part and table key part
  // Assume the following table and index structure
  // CREATE TABLE Singers (
  // SingerId INT64 NOT NULL,
  // FirstName STRING(1024),
  // LastName STRING(1024),
  // SingerInfo BYTES(MAX),
  // ) PRIMARY KEY(SingerId);
  //
  // CREATE INDEX SingersByFirstLastName ON Singers(FirstName, LastName);
  const request = [
    'CREATE INDEX IF NOT EXISTS SingersByFirstLastName ON Singers(FirstName, LastName)',
  ];

  const [operation] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    ),
    statements: request,
  });

  console.log('Waiting for operation to complete...');
  await operation.promise();

  console.log('Added the SingersByFirstLastName index.');

  databaseAdminClient.addSplitPoints({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    ),
    splitPoints: [
      {
        table: 'Singers',
        keys: [{keyParts: {values: [{stringValue: '42'}]}}],
      },
      {
        index: 'SingersByFirstLastName',
        keys: [
          {
            keyParts: {
              values: [{stringValue: 'John'}, {stringValue: 'Doe'}],
            },
          },
        ],
      },
      {
        index: 'SingersByFirstLastName',
        keys: [
          {
            keyParts: {
              values: [{stringValue: 'Jane'}, {stringValue: 'Doe'}],
            },
          },
          {keyParts: {values: [{stringValue: '38'}]}},
        ],
      },
    ],
  });
  console.log('Added Split Points');
} catch (err) {
  console.error('ERROR:', err);
}

Python

def add_split_points(instance_id, database_id):
    """Adds split points to table and index."""

    from google.cloud.spanner_admin_database_v1.types import spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_admin_api.database_path(
            spanner_client.project, instance_id, database_id
        ),
        statements=[
            "CREATE INDEX IF NOT EXISTS SingersByFirstLastName ON Singers(FirstName, LastName)"
        ],
    )

    operation = database_admin_api.update_database_ddl(request)

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Added the SingersByFirstLastName index.")

    addSplitPointRequest = spanner_database_admin.AddSplitPointsRequest(
        database=database_admin_api.database_path(
            spanner_client.project, instance_id, database_id
        ),
        # Table split
        # Index split without table key part
        # Index split with table key part: first key is the index key and second the table key
        split_points=[
            spanner_database_admin.SplitPoints(
                table="Singers",
                keys=[
                    spanner_database_admin.SplitPoints.Key(
                        key_parts=struct_pb2.ListValue(
                            values=[struct_pb2.Value(string_value="42")]
                        )
                    )
                ],
            ),
            spanner_database_admin.SplitPoints(
                index="SingersByFirstLastName",
                keys=[
                    spanner_database_admin.SplitPoints.Key(
                        key_parts=struct_pb2.ListValue(
                            values=[
                                struct_pb2.Value(string_value="John"),
                                struct_pb2.Value(string_value="Doe"),
                            ]
                        )
                    )
                ],
            ),
            spanner_database_admin.SplitPoints(
                index="SingersByFirstLastName",
                keys=[
                    spanner_database_admin.SplitPoints.Key(
                        key_parts=struct_pb2.ListValue(
                            values=[
                                struct_pb2.Value(string_value="Jane"),
                                struct_pb2.Value(string_value="Doe"),
                            ]
                        )
                    ),
                    spanner_database_admin.SplitPoints.Key(
                        key_parts=struct_pb2.ListValue(
                            values=[struct_pb2.Value(string_value="38")]
                        )
                    ),
                ],
            ),
        ],
    )

    operation = database_admin_api.add_split_points(addSplitPointRequest)

    print("Added split points.")

תרחישי שגיאה אפשריים

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

בשם הטבלה בקלט של פיצול רמת האינדקס יש שגיאה.
נקודת הפיצול ברמת הטבלה מכילה יותר ממפתח אחד.
נקודת הפיצול ברמת האינדקס מכילה יותר משני מפתחות.
נקודות הפיצול מוגדרות בטבלאות או באינדקסים שלא מוגדרים בסכימת מסד הנתונים.
הבקשה מכילה נקודות פיצול כפולות.

מידע על מכסות ומגבלות זמין במאמר מכסות ומגבלות.

צפייה בנקודות המפוצלות

אפשר לראות את כל נקודות הפיצול שנוצרו במסד הנתונים באמצעות מסוףGoogle Cloud או ה-CLI של gcloud:

המסוף

כדי לקבל את מספר נקודות הפיצול באמצעות שאילתה בתצוגה במסוף SPANNER_SYS.USER_SPLIT_POINTS Google Cloud :

פותחים את הדף 'מכונות של Spanner'.

כניסה לדף Spanner instances
בוחרים את השמות של מופע Spanner ושל מסד הנתונים שרוצים לשלוח אליהם שאילתה.
בחלונית הניווט הימנית, לוחצים על Spanner Studio.
מקלידים את השאילתה הבאה בשדה הטקסט:
```
    SELECT * FROM SPANNER_SYS.USER_SPLIT_POINTS
```
לוחצים על Run query.

יוצג לכם פלט דומה לזה:

TABLE_NAME	INDEX_NAME	INITIATOR	SPLIT_KEY	EXPIRE_TIME
T		CloudAddSplitPointsAPI	T(90,153,4,2024-04-30T17:00:00-07:00,1,2024-05-01,a)	2025-03-06T09:58:58.007201Z
T	T_IDX	CloudAddSplitPointsAPI	אינדקס: T_IDX ב-T, מפתח אינדקס: (10), מפתח טבלה ראשי: (<begin>,<begin>,<begin>,<begin>,<begin>,<begin>,<begin>)	2025-03-08T07:33:23.861682Z
T	T_IDX	CloudAddSplitPointsAPI	אינדקס: T_IDX ב-T, מפתח אינדקס: (9091), מפתח טבלה ראשי: (4567,123,4.2,2024-04-30T17:00:00-07:00,1,2024-05-01,a)	2025-03-08T07:35:25.990007Z

gcloud

מריצים את הפקודה הבאה ב-CLI של gcloud כדי לראות את נקודות הפיצול במסד הנתונים:

  gcloud spanner databases splits list DATABASE_ID \
  --instance INSTANCE_ID

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

‫INSTANCE_ID: מזהה מכונת Spanner.
‫DATABASE_ID: מזהה מסד הנתונים של Spanner.

מופיעה תגובה שדומה לזו:

  TABLE_NAME: T
  INDEX_NAME:
  INITIATOR: CloudAddSplitPointsAPI
  SPLIT_KEY: T(90,153,4,2024-04-30T17:00:00-07:00,1,2024-05-01,a)
  EXPIRE_TIME: 2025-03-06T09:58:58.007201Z

  TABLE_NAME: T
  INDEX_NAME: T_IDX
  INITIATOR: CloudAddSplitPointsAPI
  SPLIT_KEY: Index: T_IDX on T, Index Key: (10), Primary Table Key: (<begin>,<begin>,<begin>,<begin>,<begin>,<begin>,<begin>)
  EXPIRE_TIME: 2025-03-08T07:33:23.861682Z

  TABLE_NAME: T
  INDEX_NAME: T_IDX
  INITIATOR: CloudAddSplitPointsAPI
  SPLIT_KEY: Index: T_IDX on T, Index Key: (9091), Primary Table Key: (4567,123,4.2,2024-04-30T17:00:00-07:00,1,2024-05-01,a)
  EXPIRE_TIME: 2025-03-08T07:35:25.990007Z

איך מגדירים תאריך תפוגה לנקודת פיצול

אפשר להגדיר זמן תפוגה לכל נקודת פיצול שיוצרים. מידע נוסף זמין במאמר בנושא תפוגה של נקודת חלוקה. אפשר להגדיר תפוגה לנקודות פיצול באמצעות Google Cloud CLI או ממשקי ה-API ל-REST.

gcloud

אם רוצים להגדיר תאריך תפוגה לנקודות פיצול באמצעות ה-CLI של gcloud, צריך ליצור קובץ שמכיל את כל הפיצולים שרוצים להגדיר להם תאריך תפוגה, ולספק את הנתיב שלו באמצעות הפרמטר splits-file בפקודת ה-CLI של gcloud. הקובץ לא יכול לחרוג ממגבלת ה-API של 100 נקודות לכל בקשת API. מידע נוסף זמין במאמר מכסות ומגבלות.

כדי לציין את נקודות הפיצול, צריך להשתמש בפורמט הבא בקובץ:

  ObjectType ObjectName (SplitValue)
  ObjectType ObjectName (SplitValue)
  ObjectType ObjectName (SplitValue)

כשיוצרים את הקובץ, מחליפים את המשתנים הבאים:

‫ObjectType: סוג האובייקט של הפיצול שרוצים להגדיר לו תפוגה. הערכים התקינים הם TABLE ו-INDEX.
‫ObjectName: השם של טבלת מסד הנתונים או האינדקס.
‫SplitValue: ערך נקודת הפיצול שרוצים להוציא משימוש.

כשיוצרים את הערכים של נקודות הפיצול בקובץ, צריך לפעול לפי הכללים הבאים:

ערכי מחרוזות צריכים להיות במירכאות בודדות. לדוגמה, 'splitKeyPart'
הערכים הבוליאניים יכולים להיות true או false.
ערכים מסוג נתונים של Spanner‏ INT64 ו-NUMERIC צריכים להיות במירכאות בודדות. לדוגמה, '123' או '99.99'.
כל שאר הערכים המספריים צריכים להיכתב בלי גרשיים בודדים. לדוגמה, 1.287.
ערכים של חותמת זמן צריכים להיות בפורמט '2020-06-18T17:24:53Z' בגרשיים בודדים.
צריך להוסיף סוגריים מסביב לערכים המפוצלים.
הסדר של ערכי המפתחות המפוצלים צריך להיות זהה לסדר של המפתח הראשי.
אם הערך המפוצל צריך לכלול פסיק, צריך להוסיף לפני הפסיק את התו `\`.
כדי לפצל אינדקסים, אפשר לספק את מפתח האינדקס או את האינדקס כולו ואת מפתח הטבלה המלא.
כשמציינים את נקודת הפיצול, תמיד צריך להשתמש במפתח המלא.

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

  TABLE Singers ('c32ca57a-786c-2268-09d4-95182a9930be')
  TABLE Singers ('bb98c7e2-8240-b780-346d-c5d63886594a')
  INDEX Order ('5b8bac71-0cb2-95e9-e1b0-89a027525460')
  TABLE Payment ('6cf41f21-2d77-318f-c504-816f0068db8b')
  INDEX Indx_A (2152120141932780000)
  TABLE TableD  (0,'7ef9db22-d0e5-6041-8937-4bc6a7ef9db2')
  INDEX IndexXYZ ('8762203435012030000',NULL,NULL)
  INDEX IndexABC  (0, '2020-06-18T17:24:53Z', '2020-06-18T17:24:53Z') TableKey
  (123,'ab\,c')

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫SPLITS_FILE: הנתיב לקובץ הפיצולים.
‫INSTANCE_ID: מזהה המכונה.
‫DATABASE_ID: מזהה מסד הנתונים.
‫EXPIRATION_DATE: (אופציונלי) תאריך התפוגה של הנקודות המפוצלות. מקבלת חותמת זמן בפורמט '2020-06-18T17:24:53Z'.
‫INITIATOR: (אופציונלי) הגורם שיזם את נקודות הפיצול.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud spanner databases splits add DATABASE_ID \
--splits-file=SPLITS_FILE \
--instance=INSTANCE_ID \
--split-expiration-date=EXPIRATION_DATE \
--initiator=INITIATOR

‏Windows (PowerShell)

gcloud spanner databases splits add DATABASE_ID `
--splits-file=SPLITS_FILE `
--instance=INSTANCE_ID `
--split-expiration-date=EXPIRATION_DATE `
--initiator=INITIATOR

Windows‏ (cmd.exe)

gcloud spanner databases splits add DATABASE_ID ^
--splits-file=SPLITS_FILE ^
--instance=INSTANCE_ID ^
--split-expiration-date=EXPIRATION_DATE ^
--initiator=INITIATOR

REST v1

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט.
‫INSTANCE_ID: מזהה המכונה.
‫DATABASE_ID: מזהה מסד הנתונים.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints

תוכן בקשת JSON:

{
  "split_points": [
    {
      "table": "T1",
      "index": "T1_IDX",
      "expire_time": "2023-04-22T10:00:20.021Z",
      "keys": [
        {
          "key_parts": {
            "values": [
              3
            ]
          }
        },
        {
          "key_parts": {
            "values": [
              10
            ]
          }
        }
      ]
    },
    {
      "table": "T2",
      "expire_time": "2023-04-22T10:00:20.021Z",
      "keys": [
        {
          "key_parts": {
            "values": [
              50
            ]
          }
        }
      ]
    }
  ]
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints"

‎PowerShell (Windows)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://spanner.googleapis.com/v1/projects//instances//databases/:addSplitPoints" | Select-Object -Expand Content

אמור להתקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

מה השלב הבא?

סקירה כללית בנושא פיצול לפני המרה

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

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

יצירת נקודות פיצול

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST v1

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

ספריות לקוח

Go

Java

Node.js

Python

תרחישי שגיאה אפשריים

צפייה בנקודות המפוצלות

המסוף

gcloud

איך מגדירים תאריך תפוגה לנקודת פיצול

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST v1

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

מה השלב הבא?

יצירה וניהול של נקודות פיצול