/internal/storage/schema.go

package storage

import (
	"fmt"
	"strconv"

	"github.com/apache/arrow/go/v17/arrow"
	"google.golang.org/protobuf/proto"

	"github.com/milvus-io/milvus-proto/go-api/v3/schemapb"
	"github.com/milvus-io/milvus/internal/storagev2/packed"
	"github.com/milvus-io/milvus/pkg/v3/common"
	"github.com/milvus-io/milvus/pkg/v3/util/merr"
	"github.com/milvus-io/milvus/pkg/v3/util/typeutil"
)

// ArrowFieldNameResolver maps a Milvus field to the physical Arrow column name
// that should be read. Returning false skips the field.
type ArrowFieldNameResolver func(field *schemapb.FieldSchema) (string, bool)

func ConvertToArrowSchema(schema *schemapb.CollectionSchema, useFieldID bool) (*arrow.Schema, error) {
	return ConvertToArrowSchemaWithNameResolver(schema, useFieldID, nil)
}

// ConvertToArrowSchemaWithNameResolver converts a Milvus schema to Arrow and
// lets callers override physical column names for external/manifest reads.
func ConvertToArrowSchemaWithNameResolver(
	schema *schemapb.CollectionSchema,
	useFieldID bool,
	nameResolver ArrowFieldNameResolver,
) (*arrow.Schema, error) {
	fieldCount := len(typeutil.GetAllFieldSchemas(schema))
	arrowFields := make([]arrow.Field, 0, fieldCount)
	appendArrowField := func(field *schemapb.FieldSchema) error {
		physicalName := ""
		if nameResolver != nil {
			name, ok := nameResolver(field)
			if !ok {
				return nil
			}
			physicalName = name
		}
		if serdeMap[field.DataType].arrowType == nil {
			return merr.WrapErrParameterInvalidMsg("unknown field data type [%s] for field [%s]", field.DataType, field.GetName())
		}
		var dim int
		switch field.DataType {
		case schemapb.DataType_BinaryVector, schemapb.DataType_Float16Vector, schemapb.DataType_BFloat16Vector,
			schemapb.DataType_Int8Vector, schemapb.DataType_FloatVector, schemapb.DataType_ArrayOfVector:
			var err error
			dim, err = GetDimFromParams(field.TypeParams)
			if err != nil {
				return merr.WrapErrParameterInvalidMsg("dim not found in field [%s] params", field.GetName())
			}
		default:
			dim = 0
		}

		elementType := schemapb.DataType_None
		if field.DataType == schemapb.DataType_ArrayOfVector {
			elementType = field.GetElementType()
		}

		arrowType := serdeMap[field.DataType].arrowType(dim, elementType)

		if field.GetNullable() {
			switch field.DataType {
			case schemapb.DataType_BinaryVector, schemapb.DataType_FloatVector,
				schemapb.DataType_Float16Vector, schemapb.DataType_BFloat16Vector, schemapb.DataType_Int8Vector:
				arrowType = arrow.BinaryTypes.Binary
			}
		}

		arrowField := ConvertToArrowField(field, arrowType, useFieldID)
		if physicalName != "" {
			arrowField.Name = physicalName
		}

		if field.GetNullable() {
			switch field.DataType {
			case schemapb.DataType_BinaryVector, schemapb.DataType_FloatVector,
				schemapb.DataType_Float16Vector, schemapb.DataType_BFloat16Vector, schemapb.DataType_Int8Vector:
				arrowField.Metadata = arrow.NewMetadata(
					[]string{packed.ArrowFieldIdMetadataKey, "dim"},
					[]string{strconv.Itoa(int(field.GetFieldID())), strconv.Itoa(dim)},
				)
			}
		}

		// Add extra metadata for ArrayOfVector
		if field.DataType == schemapb.DataType_ArrayOfVector {
			arrowField.Metadata = arrow.NewMetadata(
				[]string{packed.ArrowFieldIdMetadataKey, "elementType", "dim"},
				[]string{strconv.Itoa(int(field.GetFieldID())), strconv.Itoa(int(elementType)), strconv.Itoa(dim)},
			)
		}

		arrowFields = append(arrowFields, arrowField)
		return nil
	}
	for _, field := range schema.GetFields() {
		if err := appendArrowField(field); err != nil {
			return nil, err
		}
	}

	for _, structField := range schema.GetStructArrayFields() {
		for _, field := range structField.GetFields() {
			if err := appendArrowField(field); err != nil {
				return nil, err
			}
		}
	}

	return arrow.NewSchema(arrowFields, nil), nil
}

// FilterRowIDFromSchema returns a deep copy of the schema with RowID system field removed.
func FilterRowIDFromSchema(schema *schemapb.CollectionSchema) *schemapb.CollectionSchema {
	filtered := proto.Clone(schema).(*schemapb.CollectionSchema)
	n := 0
	for _, f := range filtered.Fields {
		if f.FieldID != common.RowIDField {
			filtered.Fields[n] = f
			n++
		}
	}
	filtered.Fields = filtered.Fields[:n]
	return filtered
}

// overrideTextFieldsToBinary replaces utf8 arrow type with binary for TEXT fields.
// In manifest storage, TEXT fields use LOB spillover and store binary-encoded LOB references.
func overrideTextFieldsToBinary(schema *schemapb.CollectionSchema, arrowSchema *arrow.Schema) *arrow.Schema {
	return overrideTextFieldsToBinaryByFields(typeutil.GetAllFieldSchemas(schema), arrowSchema)
}

func overrideTextFieldsToBinaryByFields(allFields []*schemapb.FieldSchema, arrowSchema *arrow.Schema) *arrow.Schema {
	fields := make([]arrow.Field, arrowSchema.NumFields())
	changed := false
	for i := 0; i < arrowSchema.NumFields(); i++ {
		fields[i] = arrowSchema.Field(i)
		if i < len(allFields) && allFields[i].DataType == schemapb.DataType_Text {
			fields[i].Type = arrow.BinaryTypes.Binary
			changed = true
		}
	}
	if !changed {
		return arrowSchema
	}
	return arrow.NewSchema(fields, nil)
}

func ConvertToArrowField(field *schemapb.FieldSchema, dataType arrow.DataType, useFieldID bool) arrow.Field {
	f := arrow.Field{
		Type:     dataType,
		Metadata: arrow.NewMetadata([]string{packed.ArrowFieldIdMetadataKey}, []string{strconv.Itoa(int(field.GetFieldID()))}),
		Nullable: field.GetNullable(),
	}
	// external field name has higher priority
	if field.GetExternalField() != "" {
		f.Name = field.GetExternalField()
	} else if useFieldID { // use fieldID as name when specified
		f.Name = fmt.Sprintf("%d", field.GetFieldID())
	} else {
		f.Name = field.GetName()
	}
	return f
}