Data API client upgrade guide

# Before 2.0-preview
collection = database.create_collection(
    "my_collection",
    dimension=3,
    metric=VectorMetric.DOT_PRODUCT,
    indexing={"deny": ["annotations", "logs"]},
)

# 2.0-preview and later, fluent interface
collection = database.create_collection(
    "my_collection",
    definition=(
        CollectionDefinition.builder()
        .set_vector_dimension(3)
        .set_vector_metric(VectorMetric.DOT_PRODUCT)
        .set_indexing("deny", ["annotations", "logs"])
        .build()
    ),

)

# 2.0-preview and later, CollectionDefinition object
collection = database.create_collection(
    "my_collection",
    definition=CollectionDefinition(
        vector=CollectionVectorOptions(
            dimension=3,
            metric=VectorMetric.DOT_PRODUCT,
        ),
        indexing={"deny": ["annotations", "logs"]},
    ),
)

# 2.0-preview and later, dictionary equivalent to CollectionDefinition
collection = database.create_collection(
    "my_collection",
    definition= {
        "vector": {
            "dimension": 3,
            "metric": VectorMetric.DOT_PRODUCT,
        },
        "indexing": {"deny": ["annotations", "logs"]},
    },
)

// Before 2.0-preview
Collection<Document> collectionBefore2 = database
 .createCollection("col1", CollectionOptions
   .builder()
   .vectorDimension(14)
   .vectorSimilarity(SimilarityMetric.COSINE)
   .build());

// 2.0-preview and later
Collection<Document> collection = database
 .createCollection("col1", new CollectionDefinition()
  .vectorDimension(14)
  .vectorSimilarity(SimilarityMetric.COSINE)
);

// No specialization, default Object Document
Collection<Document> col1 = db
  .createCollection("col1");

// No specialization, custom Document bean
Collection<Bean> col2 = db
  .createCollection("col2", Bean.class);

// Specialized collection, default Document
CollectionDefinition def = new CollectionDefinition()
  .vectorDimension(14)
  .vectorSimilarity(SimilarityMetric.COSINE);
Collection<Document> col3 = db
  .createCollection("col2", def);

// Specialized collection, custom Document bean
Collection<Bean> col4 = db
  .createCollection("col4", def, Bean.class);

// Add options for creation
CreateCollectionOptions options = new CreateCollectionOptions()
    .timeout(30000);
Collection<Bean> col5 = db
  .createCollection("col5", def, Bean.class, options);

# Before 2.0-preview
my_collection.insert_many(..., max_time_ms=40000)

# 2.0-preview and later
my_collection.insert_many(..., timeout_ms=40000)

from astrapy.api_options import APIOptions, TimeoutOptions

my_slow_collection = database.get_collection(
    "reports",
    spawn_api_options=APIOptions(
        timeout_options=TimeoutOptions(
            request_timeout_ms=20000,
            general_method_timeout_ms=40000,
        ),
    ),
)
my_slow_collection.insert_many(...)

my_collection.insert_one(..., request_timeout_ms=12000)
my_collection.insert_many(
    ...,
    general_method_timeout_ms=40000,
    request_timeout_ms=12000,
)

my_database_admin.create_keyspace(..., keyspace_admin_timeout_ms=30000)
# Equivalent using timeout_ms.
my_database_admin.create_keyspace(..., timeout_ms=30000)

// Before 2.0-preview
await collection.insertMany(..., { maxTimeMS: 40000 });

// 2.0-preview and later
await collection.insertMany(..., { timeout: 40000 });

const mySlowCollection = db.collection("reports", {
  timeoutDefaults: {
    requestTimeoutMs: 20000,
    generalMethodTimeoutMs: 40000,
  },
});

await collection.insertOne(..., {
  timeout: { requestTimeoutMs: 12000 },
});

await collection.insertMany(..., {
  timeout: {
    generalMethodTimeoutMs: 40000,
    requestTimeoutMs: 12000,
  },
});

// Both equivalent here
await db.createKeyspace(..., { keyspaceAdminTimeoutMs: 30000 });
await db.createKeyspace(..., { timeout: 30000 });

// Definition timeout at 5000 millis for operation 'findOne'
CollectionFindOneOptions options1 = new CollectionFindOneOptions()
  .timeout(5000L);
collect.findOne(myFilter, options2);

// Same timeout using a Duration object
CollectionFindOneOptions options2 = new CollectionFindOneOptions()
  .timeout(Duration.ofSeconds(5));

TimeoutOptions fullFledgesTimeouts = new TimeoutOptions()
  .generalMethodTimeoutMillis(50000)
  .requestTimeoutMillis(2000);
CollectionFindOneOptions options3 = new CollectionFindOneOptions()
  .timeoutOptions(fullFledgesTimeouts);
collect.insertMany( ..., options3)

# Before 1.5
database = client.get_database("API_ENDPOINT", namespace="NAMESPACE_OR_KEYSPACE_NAME")

# 1.5 and later
database = client.get_database("API_ENDPOINT", keyspace="NAMESPACE_OR_KEYSPACE_NAME")

// Before 1.5
const db = client.db('API_ENDPOINT', { namespace: 'NAMESPACE_OR_KEYSPACE_NAME' });

// 1.5 and later
const db = client.db('API_ENDPOINT', { keyspace: 'NAMESPACE_OR_KEYSPACE_NAME' });

import java.time.Duration;// Before 1.5
Database db = client.getDatabase(String apiEndpoint, String namespace);

// 1.5 and later
Database db = client.getDatabase(String apiEndpoint, String keyspace);

// Second argument can be a DatabaseOptions to specialize even more the database object
DatabaseOptions dbOptions = new DatabaseOptions(token, options)
 .keyspace(keyspace)
 .token("anotherToken")
 .timeout(Duration.ofSeconds(10));
Database db = client.getDatabase(String apiEndpoint ,dbOptions);

curl -sS -L -X POST "ASTRA_DB_ENDPOINT/api/json/v1/NAMESPACE_OR_KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{DATA_API_COMMAND_BODY}'

# Before 1.5.1, the following are all valid:
database = client.get_database("API_ENDPOINT")
database = client.get_database("ID")
database = client["API_ENDPOINT"]
database = client["ID"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")
database = client.get_database("ID", keyspace="KEYSPACE_NAME", region="REGION")

# At 1.5.1 and later, use only 'API_ENDPOINT':
database = client.get_database("API_ENDPOINT")
database = client["API_ENDPOINT"]
database = client.get_database("API_ENDPOINT", keyspace="KEYSPACE_NAME")

// Before 1.5.1, the following are all valid:
const db = client.db('API_ENDPOINT');
const db = client.db('ID', 'REGION');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });
const db = client.db('ID', 'REGION', { keyspace: 'KEYSPACE_NAME' });

// At 1.5.1 and later, use only 'API_ENDPOINT':
const db = client.db('API_ENDPOINT');
const db = client.db('API_ENDPOINT', { keyspace: 'KEYSPACE_NAME' });

// Syntax before 1.5
Database db = client.getDatabase(String apiEndpoint);
Database db = client.getDatabase(UUID databaseId, String region);
Database db = client.getDatabase(String apiEndpoint, String keyspace);
Database db = client.getDatabase(UUID databaseId, String region, String keyspace);

// Syntax slightly different after 1.5 (keyspace is now an option)
Database db = client.getDatabase(String apiEndpoint, DatabaseOptions options);
Database db = client.getDatabase(UUID databaseId, DatabaseOptions options);
Database db = client.getDatabase(UUID databaseId, String region, DatabaseOptions options);

curl -sS -L -X POST "ASTRA_DB_ENDPOINT/api/json/v1/KEYSPACE_NAME"