diff --git a/CHANGELOG.md b/CHANGELOG.md index 1db3c76f..cf7788e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [1.16.0](https://github.com/googleapis/python-spanner-sqlalchemy/compare/v1.15.0...v1.16.0) (2025-09-02) + + +### Features + +* Support NULL FILTERED indexes ([#750](https://github.com/googleapis/python-spanner-sqlalchemy/issues/750)) ([4bc0589](https://github.com/googleapis/python-spanner-sqlalchemy/commit/4bc05898995a586816e116e0a3205966a52d1ef8)) + + +### Documentation + +* Add sample for parse_json ([#752](https://github.com/googleapis/python-spanner-sqlalchemy/issues/752)) ([b2f0e89](https://github.com/googleapis/python-spanner-sqlalchemy/commit/b2f0e89b8f01481fa6f29da055300eeb533591cc)), closes [#735](https://github.com/googleapis/python-spanner-sqlalchemy/issues/735) + ## [1.15.0](https://github.com/googleapis/python-spanner-sqlalchemy/compare/v1.14.0...v1.15.0) (2025-08-19) 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/google/cloud/sqlalchemy_spanner/version.py b/google/cloud/sqlalchemy_spanner/version.py index a55a585c..66d505de 100644 --- a/google/cloud/sqlalchemy_spanner/version.py +++ b/google/cloud/sqlalchemy_spanner/version.py @@ -4,4 +4,4 @@ # license that can be found in the LICENSE file or at # https://developers.google.com/open-source/licenses/bsd -__version__ = "1.15.0" +__version__ = "1.16.0" diff --git a/requirements.txt b/requirements.txt index 843c977b..79fe090d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,9 +4,9 @@ # # pip-compile --generate-hashes # -alembic==1.16.4 \ - --hash=sha256:b05e51e8e82efc1abd14ba2af6392897e145930c3e0a2faf2b0da2f7f7fd660d \ - --hash=sha256:efab6ada0dd0fae2c92060800e0bf5c1dc26af15a10e02fb4babff164b4725e2 +alembic==1.16.5 \ + --hash=sha256:a88bb7f6e513bd4301ecf4c7f2206fe93f9913f9b48dac3b78babde2d6fe765e \ + --hash=sha256:e845dfe090c5ffa7b92593ae6687c5cb1a101e91fa53868497dbd79847f9dbe3 # via -r requirements.in build==1.3.0 \ --hash=sha256:698edd0ea270bde950f53aed21f3a0135672206f3911e0176261a31e0e07b397 \ @@ -14,9 +14,9 @@ build==1.3.0 \ # via # -r requirements.in # pip-tools -cachetools==6.1.0 \ - --hash=sha256:1c7bb3cf9193deaf3508b7c5f2a79986c13ea38965c5adcff1f84519cf39163e \ - --hash=sha256:b4c4f404392848db3ce7aac34950d17be4d864da4b8b66911008e430bc544587 +cachetools==6.2.0 \ + --hash=sha256:1c76a8960c0041fcc21097e357f882197c79da0dbff766e7317890a65d7d8ba6 \ + --hash=sha256:38b328c0889450f05f5e120f56ab68c8abaf424e1275522b138ffc93253f7e32 # via google-auth certifi==2025.8.3 \ --hash=sha256:e564105f78ded564e3ae7c923924435e1daa7463faeab5bb932bc53ffae63407 \ @@ -527,9 +527,9 @@ tomli==2.2.1 \ --hash=sha256:ece47d672db52ac607a3d9599a9d48dcb2f2f735c6c2d1f34130085bb12b112a \ --hash=sha256:f4039b9cbc3048b2416cc57ab3bda989a6fcf9b36cf8937f01a6e731b64f80d7 # via -r requirements.in -typing-extensions==4.14.1 \ - --hash=sha256:38b39f4aeeab64884ce9f74c94263ef78f3c22467c8724005483154c26648d36 \ - --hash=sha256:d1e1e3b58374dc93031d6eda2420a48ea44a36c2b4766a4fdeb3710755731d76 +typing-extensions==4.15.0 \ + --hash=sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466 \ + --hash=sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548 # via # alembic # opentelemetry-api diff --git a/samples/noxfile.py b/samples/noxfile.py index cd28a3f0..29709cd1 100644 --- a/samples/noxfile.py +++ b/samples/noxfile.py @@ -97,6 +97,11 @@ def insertmany(session): _sample(session) +@nox.session() +def parse_json(session): + _sample(session) + + @nox.session() def _all_samples(session): _sample(session) 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/samples/parse_json_sample.py b/samples/parse_json_sample.py new file mode 100644 index 00000000..b0868ea8 --- /dev/null +++ b/samples/parse_json_sample.py @@ -0,0 +1,50 @@ +# 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, func, text +from sqlalchemy.orm import Session + +from sample_helper import run_sample +from model import Venue + +# Shows how to use the PARSE_JSON function in Spanner using SQLAlchemy. +def parse_json_sample(): + engine = create_engine( + "spanner:///projects/sample-project/" + "instances/sample-instance/" + "databases/sample-database", + echo=True, + ) + with Session(engine) as session: + venue = Venue( + code="LCH", + active=True, + name="Large Concert Hall", + # The SQLAlchemy func function is very lenient and allows you to call any + # database function that Spanner supports. Use a text instance to add a + # specific SQL fragment to the function call. + description=func.parse_json( + '{"type": "Stadium", "size": 13.7391432}', + text("wide_number_mode=>'round'"), + ), + ) + session.add(venue) + session.commit() + + venue = session.query(Venue).filter_by(code="LCH").one() + print(venue.description) + + +if __name__ == "__main__": + run_sample(parse_json_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_json.py b/test/mockserver_tests/test_json.py index 2d37a335..244e5d62 100644 --- a/test/mockserver_tests/test_json.py +++ b/test/mockserver_tests/test_json.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -from sqlalchemy import select +from sqlalchemy import func, select, text from sqlalchemy.orm import Session from sqlalchemy.testing import eq_, is_instance_of from google.cloud.spanner_v1 import ( @@ -73,7 +73,24 @@ def test_insert_array(self): '[{"size":"Great","type":"Stadium"}]', ) - def _test_insert_json(self, description, expected): + def test_insert_fn(self): + add_update_count( + "INSERT INTO venues (id, name, description) " + "VALUES (@a0, @a1, parse_json(@a2, wide_number_mode=>'round'))", + 1, + ) + self._test_insert_json( + func.parse_json( + '{"type": "Stadium", "size": "Great"}', + text("wide_number_mode=>'round'"), + ), + '{"type": "Stadium", "size": "Great"}', + expected_type_code=TypeCode.STRING, + ) + + def _test_insert_json( + self, description, expected, expected_type_code=TypeCode.JSON + ): from test.mockserver_tests.json_model import Venue add_update_count( @@ -100,7 +117,7 @@ def _test_insert_json(self, description, expected): eq_(expected, request.params["a2"]) eq_(TypeCode.INT64, request.param_types["a0"].code) eq_(TypeCode.STRING, request.param_types["a1"].code) - eq_(TypeCode.JSON, request.param_types["a2"].code) + eq_(expected_type_code, request.param_types["a2"].code) def test_select_dict(self): self._test_select_json( 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], + )