diff --git a/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py b/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py index 480747b0..4ab387a9 100644 --- a/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py +++ b/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py @@ -718,6 +718,15 @@ def visit_create_index( text += " STORING (%s)" % ", ".join( [self.preparer.quote(c.name) for c in storing_columns] ) + + if options.get("null_filtered", False): + text = re.sub( + r"(^\s*CREATE\s+(?:UNIQUE\s+)?)INDEX", + r"\1NULL_FILTERED INDEX", + text, + flags=re.IGNORECASE, + ) + return text def get_identity_options(self, identity_options): diff --git a/samples/null_filtered_index.py b/samples/null_filtered_index.py new file mode 100644 index 00000000..d8d9556f --- /dev/null +++ b/samples/null_filtered_index.py @@ -0,0 +1,75 @@ +# Copyright 2025 Google LLC All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import uuid + +from sqlalchemy import create_engine, Index +from sqlalchemy.exc import IntegrityError +from sqlalchemy.orm import mapped_column, DeclarativeBase, Mapped, Session + +from sample_helper import run_sample + +# Shows how to create a null-filtered index. +# +# A null-filtered index does not index NULL values. This is useful for +# maintaining smaller indexes over sparse columns. +# https://cloud.google.com/spanner/docs/secondary-indexes#null-indexing-disable + + +class Base(DeclarativeBase): + pass + + +class Singer(Base): + __tablename__ = "singers_with_null_filtered_index" + __table_args__ = ( + Index("uq_null_filtered_name", "name", unique=True, spanner_null_filtered=True), + ) + + id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4())) + name: Mapped[str | None] + + +def null_filtered_index_sample(): + engine = create_engine( + "spanner:///projects/sample-project/" + "instances/sample-instance/" + "databases/sample-database", + echo=True, + ) + Base.metadata.create_all(engine) + + # We can create singers with a name of jdoe and NULL. + with Session(engine) as session: + session.add(Singer(name="jdoe")) + session.add(Singer(name=None)) + session.commit() + + # The unique index will stop us from adding another jdoe. + with Session(engine) as session: + session.add(Singer(name="jdoe")) + try: + session.commit() + except IntegrityError: + session.rollback() + + # The index is null filtered, so we can still add another + # NULL name. The NULL values are not part of the index. + with Session(engine) as session: + session.add(Singer(name=None)) + session.commit() + + +if __name__ == "__main__": + run_sample(null_filtered_index_sample) diff --git a/test/mockserver_tests/null_filtered_index.py b/test/mockserver_tests/null_filtered_index.py new file mode 100644 index 00000000..e4ca5d69 --- /dev/null +++ b/test/mockserver_tests/null_filtered_index.py @@ -0,0 +1,37 @@ +# Copyright 2025 Google LLC All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from sqlalchemy import Index +from sqlalchemy.orm import DeclarativeBase +from sqlalchemy.orm import Mapped +from sqlalchemy.orm import mapped_column + + +class Base(DeclarativeBase): + pass + + +class Singer(Base): + __tablename__ = "singers" + __table_args__ = ( + Index("idx_name", "name"), + Index("idx_uq_name", "name", unique=True), + Index("idx_null_filtered_name", "name", spanner_null_filtered=True), + Index( + "idx_uq_null_filtered_name", "name", unique=True, spanner_null_filtered=True + ), + ) + + id: Mapped[str] = mapped_column(primary_key=True) + name: Mapped[str] diff --git a/test/mockserver_tests/test_null_filtered_index.py b/test/mockserver_tests/test_null_filtered_index.py new file mode 100644 index 00000000..28ed1b5d --- /dev/null +++ b/test/mockserver_tests/test_null_filtered_index.py @@ -0,0 +1,80 @@ +# Copyright 2025 Google LLC All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from sqlalchemy import create_engine +from sqlalchemy.testing import eq_, is_instance_of +from google.cloud.spanner_v1 import ( + FixedSizePool, + ResultSet, +) +from test.mockserver_tests.mock_server_test_base import ( + MockServerTestBase, + add_result, +) +from google.cloud.spanner_admin_database_v1 import UpdateDatabaseDdlRequest + + +class TestNullFilteredIndex(MockServerTestBase): + """Ensure we emit correct DDL for not null filtered indexes.""" + + def test_create_table(self): + from test.mockserver_tests.null_filtered_index import Base + + add_result( + """SELECT true +FROM INFORMATION_SCHEMA.TABLES +WHERE TABLE_SCHEMA="" AND TABLE_NAME="singers" +LIMIT 1 +""", + ResultSet(), + ) + add_result( + """SELECT true +FROM INFORMATION_SCHEMA.TABLES +WHERE TABLE_SCHEMA="" AND TABLE_NAME="albums" +LIMIT 1 +""", + ResultSet(), + ) + engine = create_engine( + "spanner:///projects/p/instances/i/databases/d", + connect_args={"client": self.client, "pool": FixedSizePool(size=10)}, + ) + Base.metadata.create_all(engine) + requests = self.database_admin_service.requests + eq_(1, len(requests)) + is_instance_of(requests[0], UpdateDatabaseDdlRequest) + eq_(5, len(requests[0].statements)) + eq_( + "CREATE TABLE singers (\n" + "\tid STRING(MAX) NOT NULL, \n" + "\tname STRING(MAX) NOT NULL\n" + ") PRIMARY KEY (id)", + requests[0].statements[0], + ) + + # The order of the CREATE INDEX statements appears to be + # arbitrary, so we sort it for test consistency. + index_statements = sorted(requests[0].statements[1:]) + eq_("CREATE INDEX idx_name ON singers (name)", index_statements[0]) + eq_( + "CREATE NULL_FILTERED INDEX idx_null_filtered_name ON singers (name)", + index_statements[1], + ) + eq_("CREATE UNIQUE INDEX idx_uq_name ON singers (name)", index_statements[2]) + eq_( + "CREATE UNIQUE NULL_FILTERED INDEX " + "idx_uq_null_filtered_name ON singers (name)", + index_statements[3], + )