Skip to content

Mappings

The mappings object is a parameter (mappings) for an add_documents call. Mappings can be used for granular control over a field. Currently, it is only supported for the multimodal_combination and custom_vector field types.

When creating a structured index you define weights for a multimodal field under dependent fields. When adding documents mappings is optional with structured indexes and is only needed if the user needs to override default multimodal weights defined at index creation time.

Mappings is used to define custom_vector fields for unstructured indexes only. For structured indexes, do not include custom_vector fields in mappings. Instead, declare them as fields during index creation.


Mappings object

Multimodal Combination Mappings

Defining the mapping for multimodal_combination fields:

my_mappings = {
    "my_combination_field": {
        "type": "multimodal_combination",
        "weights": {"My_image": 0.5, "Some_text": 0.5},
    },
    "my_2nd_combination_field": {
        "type": "multimodal_combination",
        "weights": {"Title": -2.5, "Description": 0.3},
    },
}

Custom Vector Mappings

Defining the mapping for custom_vector fields (in an unstructured index):

my_mappings = {
    "my_custom_audio_vector_1": {"type": "custom_vector"},
    "my_custom_audio_vector_2": {"type": "custom_vector"},
}

Adding custom vector documents using that mapping object:

Unstructured Index

# Random vectors for example purposes. replace these with your own.
example_vector_1 = [i for i in range(512)]
example_vector_2 = [1 / (i + 1) for i in range(512)]

# Create the unstructured index
mq = marqo.Client("http://localhost:8882", api_key=None)
settings = {
    "type": "unstructured",
    "model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
}
mq.create_index("my-custom-vector-index", settings_dict=settings)

# Add the custom vectors
mq.index("my-custom-vector-index").add_documents(
    documents=[
        {
            "_id": "doc1",
            "my_custom_audio_vector_1": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_1,
                "content": "Singing audio file",
            },
        },
        {
            "_id": "doc2",
            "my_custom_audio_vector_2": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_2,
                "content": "Podcast audio file",
            },
        },
    ],
    tensor_fields=["my_custom_audio_vector_1", "my_custom_audio_vector_2"],
    mappings=my_mappings,
)

For Marqo Cloud, you will need to access the endpoint of your index and replace your_endpoint with this. To do this, visit Find Your Endpoint. You will also need your API Key. To obtain this key visit Find Your API Key.

# Random vectors for example purposes. replace these with your own.
example_vector_1 = [i for i in range(512)]
example_vector_2 = [1 / (i + 1) for i in range(512)]

# Create the unstructured index
mq = marqo.Client("https://api.marqo.ai", api_key="XXXXXXXXXXXXXXX")
settings = {
    "type": "unstructured",
    "model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
}
mq.create_index("my-custom-vector-index", settings_dict=settings)

# Add the custom vectors
mq.index("my-custom-vector-index").add_documents(
    documents=[
        {
            "_id": "doc1",
            "my_custom_audio_vector_1": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_1,
                "content": "Singing audio file",
            },
        },
        {
            "_id": "doc2",
            "my_custom_audio_vector_2": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_2,
                "content": "Podcast audio file",
            },
        },
    ],
    tensor_fields=["my_custom_audio_vector_1", "my_custom_audio_vector_2"],
    mappings=my_mappings,
)

Structured Index

# Random vectors for example purposes. replace these with your own.
example_vector_1 = [i for i in range(512)]
example_vector_2 = [1 / (i + 1) for i in range(512)]

# Create the structured index
mq = marqo.Client("http://localhost:8882", api_key=None)
settings = {
    "type": "structured",
    "model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
    "allFields": [
        {"name": "my_custom_audio_vector_1", "type": "custom_vector"},
        {"name": "my_custom_audio_vector_2", "type": "custom_vector"},
    ],
    "tensorFields": ["my_custom_audio_vector_1", "my_custom_audio_vector_2"],
}
mq.create_index("my-structured-custom-vector-index", settings_dict=settings)

# Add the custom vectors
mq.index("my-structured-custom-vector-index").add_documents(
    documents=[
        {
            "_id": "doc1",
            "my_custom_audio_vector_1": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_1,
                "content": "Singing audio file",
            },
        },
        {
            "_id": "doc2",
            "my_custom_audio_vector_2": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_2,
                "content": "Podcast audio file",
            },
        },
    ]
)

For Marqo Cloud, you will need to access the endpoint of your index and replace your_endpoint with this. To do this, visit Find Your Endpoint. You will also need your API Key. To obtain this key visit Find Your API Key.

# Random vectors for example purposes. replace these with your own.
example_vector_1 = [i for i in range(512)]
example_vector_2 = [1 / (i + 1) for i in range(512)]

# Create the structured index
mq = marqo.Client("https://api.marqo.ai", api_key="XXXXXXXXXXXXXXX")
settings = {
    "type": "structured",
    "model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
    "allFields": [
        {"name": "my_custom_audio_vector_1", "type": "custom_vector"},
        {"name": "my_custom_audio_vector_2", "type": "custom_vector"},
    ],
    "tensorFields": ["my_custom_audio_vector_1", "my_custom_audio_vector_2"],
}
mq.create_index("my-structured-custom-vector-index", settings_dict=settings)

# Add the custom vectors
mq.index("my-structured-custom-vector-index").add_documents(
    documents=[
        {
            "_id": "doc1",
            "my_custom_audio_vector_1": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_1,
                "content": "Singing audio file",
            },
        },
        {
            "_id": "doc2",
            "my_custom_audio_vector_2": {
                # Put your own vector (of correct length) here.
                "vector": example_vector_2,
                "content": "Podcast audio file",
            },
        },
    ]
)