‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

gcloud

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

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

  ObjectType ObjectName (SplitValue1, SplitValue2, ...)
  ObjectType ObjectName (IndexSplitValue1, ...) TableKey (TableSplitValue1, ...)

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

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

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

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

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

  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

אפשר להשתמש ב-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) ותגובה ריקה.

ספריות לקוח

המשך


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.")

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

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

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

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

הצגת נקודות הפיצול

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

המסוף

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

פותחים את הדף Spanner instances.

כניסה לדף 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

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

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

gcloud

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

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

  ObjectType ObjectName (SplitValue1, SplitValue2, ...)
  ObjectType ObjectName (IndexSplitValue1, ...) TableKey (TableSplitValue1, ...)

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

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

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

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

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

  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)

ספריות לקוח

המשך

Java

Node.js

Python

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

הצגת נקודות הפיצול

המסוף

gcloud

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

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST v1

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

‎PowerShell (Windows)

מה השלב הבא?

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