# Migration Guide: Prior Versions to Current SDK

This guide helps you migrate from prior versions of the Pinecone Python SDK to the current release.

## Overview

The current SDK provides a modern, type-safe interface with improved performance and better developer experience. Most changes are improvements, but some APIs have evolved for clarity and consistency.

## Vector Upsert Formats

The SDK maintains backward compatibility with tuple formats from prior versions for easy migration.

### Supported Formats

**Prior SDK formats (still supported):**

```python
# 2-tuple format: (id, values)
index.upsert([
    ("id1", [0.1, 0.2, 0.3]),
    ("id2", [0.4, 0.5, 0.6]),
])

# 3-tuple format: (id, values, metadata)
index.upsert([
    ("id1", [0.1, 0.2, 0.3], {"genre": "action"}),
    ("id2", [0.4, 0.5, 0.6], {"genre": "comedy"}),
])
```

**Current format (recommended):**

```python
# Dict format - clearer and supports sparse vectors
index.upsert([
    {"id": "id1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "action"}},
    {"id": "id2", "values": [0.4, 0.5, 0.6], "sparseValues": {"indices": [0, 2], "values": [0.5, 0.3]}},
])
```

### Migration Path

**No changes required.** Tuple formats work as-is. However, we recommend migrating to dict format for:

- **Better readability** - Named fields are clearer than positional arguments
- **Better performance** - Dict format avoids normalization overhead
- **Sparse vector support** - Tuples don't support sparse vectors; dicts do
- **Type safety** - IDEs provide better autocomplete and validation with dicts

### Mixed Formats

You can mix formats in a single upsert call during migration:

```python
index.upsert([
    ("old-1", [0.1, 0.2]),  # 2-tuple
    ("old-2", [0.3, 0.4], {"type": "old"}),  # 3-tuple
    {"id": "new-1", "values": [0.5, 0.6], "metadata": {"type": "new"}},  # dict (recommended)
])
```

## Additional Changes

_This section will be expanded as more v2 features are released._

## Getting Help

- **Documentation**: [Read the Docs](https://sdk.pinecone.io/)
- **GitHub Issues**: [Report bugs or request features](https://github.com/pinecone-io/pinecone-python-client/issues)
- **Community**: [Join the Pinecone Community](https://community.pinecone.io/)
