多くのヌル可能整数を1:1からバイナリ文字列に変換する最速の方法は何ですか?


14

ワークロードの一部では、不気味なハッシュアルゴリズム実装するCLR関数を使用して行を比較し、列の値が変更されたかどうかを確認します。CLR関数はバイナリ文字列を入力として受け取るため、行をバイナリ文字列に変換する高速な方法が必要です。全ワークロード中に約100億行をハッシュすると予想されるため、このコードを可能な限り高速にしたいと思います。

異なるスキーマを持つ約300のテーブルがあります。この質問の目的のために、32のNULL入力可能INT列の単純なテーブル構造を想定してください。サンプルデータと、この質問の最後に結果をベンチマークする方法を提供しました。

すべての列の値が同じ場合、行は同じバイナリ文字列に変換する必要があります。列の値が異なる場合、行は異なるバイナリ文字列に変換する必要があります。たとえば、次のような単純なコードは機能しません。

CAST(COL1 AS BINARY(4)) + CAST(COL2 AS BINARY(4)) + ..

NULLを正しく処理しません。場合COL1NULLが行1のためのものであり、COL2行2のためにNULLである、両方の行がNULL文字列に変換されます。NULLを正しく処理することは、行全体を正しく変換することの最も難しい部分だと思います。INT列に許可されるすべての値が可能です。

質問を先取りするには:

  • それが重要な場合、ほとんどの時間(90%+)の列はNULLになりません。
  • CLRを使用する必要があります。
  • この数の行をハッシュする必要があります。ハッシュを維持できません。
  • CLR関数があるため、変換にバッチモードを使用できないと思います。

32個のNULL可能INT列をBINARY(X)or VARBINARY(X)文字列に変換する最速の方法は何ですか?

約束どおりのサンプルデータとコード:

-- create sample data
DROP TABLE IF EXISTS dbo.TABLE_OF_32_INTS;

CREATE TABLE dbo.TABLE_OF_32_INTS (
    COL1 INT NULL,
    COL2 INT NULL,
    COL3 INT NULL,
    COL4 INT NULL,
    COL5 INT NULL,
    COL6 INT NULL,
    COL7 INT NULL,
    COL8 INT NULL,
    COL9 INT NULL,
    COL10 INT NULL,
    COL11 INT NULL,
    COL12 INT NULL,
    COL13 INT NULL,
    COL14 INT NULL,
    COL15 INT NULL,
    COL16 INT NULL,
    COL17 INT NULL,
    COL18 INT NULL,
    COL19 INT NULL,
    COL20 INT NULL,
    COL21 INT NULL,
    COL22 INT NULL,
    COL23 INT NULL,
    COL24 INT NULL,
    COL25 INT NULL,
    COL26 INT NULL,
    COL27 INT NULL,
    COL28 INT NULL,
    COL29 INT NULL,
    COL30 INT NULL,
    COL31 INT NULL,
    COL32 INT NULL
);

INSERT INTO dbo.TABLE_OF_32_INTS WITH (TABLOCK)
SELECT 0, 123, 12345, 1234567, 123456789
, 0, 123, 12345, 1234567, 123456789
, 0, 123, 12345, 1234567, 123456789
, 0, 123, 12345, 1234567, 123456789
, 0, 123, 12345, 1234567, 123456789
, 0, 123, 12345, 1234567, 123456789
, NULL, -876545321
FROM
(
    SELECT TOP (1000000) ROW_NUMBER() OVER (ORDER BY (SELECT NULL)) RN
    FROM master..spt_values t1
    CROSS JOIN master..spt_values t2
) q
OPTION (MAXDOP 1);


GO


-- procedure to test performance
CREATE OR ALTER PROCEDURE #p AS 
BEGIN

SET NOCOUNT ON;

DECLARE
@counter INT = 0,
@dummy VARBINARY(8000);

WHILE @counter < 10
BEGIN
    SELECT @dummy = -- this code is clearly incomplete as it does not handle NULLs
        CAST(COL1 AS BINARY(4)) + 
        CAST(COL2 AS BINARY(4)) + 
        CAST(COL3 AS BINARY(4)) + 
        CAST(COL4 AS BINARY(4)) + 
        CAST(COL5 AS BINARY(4)) + 
        CAST(COL6 AS BINARY(4)) + 
        CAST(COL7 AS BINARY(4)) + 
        CAST(COL8 AS BINARY(4)) + 
        CAST(COL9 AS BINARY(4)) + 
        CAST(COL10 AS BINARY(4)) + 
        CAST(COL11 AS BINARY(4)) + 
        CAST(COL12 AS BINARY(4)) + 
        CAST(COL13 AS BINARY(4)) + 
        CAST(COL14 AS BINARY(4)) + 
        CAST(COL15 AS BINARY(4)) + 
        CAST(COL16 AS BINARY(4)) + 
        CAST(COL17 AS BINARY(4)) + 
        CAST(COL18 AS BINARY(4)) + 
        CAST(COL19 AS BINARY(4)) + 
        CAST(COL20 AS BINARY(4)) + 
        CAST(COL21 AS BINARY(4)) + 
        CAST(COL22 AS BINARY(4)) + 
        CAST(COL23 AS BINARY(4)) + 
        CAST(COL24 AS BINARY(4)) + 
        CAST(COL25 AS BINARY(4)) + 
        CAST(COL26 AS BINARY(4)) + 
        CAST(COL27 AS BINARY(4)) + 
        CAST(COL28 AS BINARY(4)) + 
        CAST(COL29 AS BINARY(4)) + 
        CAST(COL30 AS BINARY(4)) + 
        CAST(COL31 AS BINARY(4)) + 
        CAST(COL32 AS BINARY(4))
    FROM dbo.TABLE_OF_32_INTS
    OPTION (MAXDOP 1);

    SET @counter = @counter + 1;
END;

SELECT cpu_time
FROM sys.dm_exec_requests
WHERE session_id = @@SPID;

END;

GO

-- run procedure
EXEC #p;

(このバイナリ結果で不気味なハッシュを使用します。ワークロードはハッシュ結合を使用し、ハッシュ値はハッシュビルドの1つに使用されます。メモリ。)

回答:


6

BINARY(5)NULLを使用してINTの範囲外のものに変換することについてはどうですか。

SELECT @dummy =
    ISNULL(CAST(COL1  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL2  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL3  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL4  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL5  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL6  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL7  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL8  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL9  AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL10 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL11 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL12 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL13 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL14 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL15 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL16 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL17 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL18 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL19 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL20 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL21 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL22 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL23 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL24 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL25 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL26 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL27 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL28 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL29 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL30 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL31 AS BINARY(5)), 0x0100000000) + 
    ISNULL(CAST(COL32 AS BINARY(5)), 0x0100000000)
FROM dbo.TABLE_OF_32_INTS
OPTION (MAXDOP 1);

11

私のマシン(SQL Server 2017)では、次のC#SQLCLR関数は、binary(5)アイデアよりも約30%高速CONCAT_WS、自己応答の半分の時間で35%高速に実行されます。

UNSAFE許可が必要であり、ポインターを使用します。実装は、テストデータに非常に明確に関連付けられています。

テストの目的で、この安全でないアセンブリを機能させる最も簡単な方法は、データベースを設定し、必要に応じTRUSTWORTHYclr strictセキュリティ構成オプションを無効にすることです。

コンパイル済みコード

便宜上、CREATE ASSEMBLYコンパイルされたビットはhttps://gist.github.com/SQLKiwi/72d01b661c74485900e7ebcfdc63ab8eにあります

T-SQL関数スタブ

CREATE FUNCTION dbo.NullableIntsToBinary
(
    @Col01 int, @Col02 int, @Col03 int, @Col04 int, @Col05 int, @Col06 int, @Col07 int, @Col08 int, 
    @Col09 int, @Col10 int, @Col11 int, @Col12 int, @Col13 int, @Col14 int, @Col15 int, @Col16 int, 
    @Col17 int, @Col18 int, @Col19 int, @Col20 int, @Col21 int, @Col22 int, @Col23 int, @Col24 int, 
    @Col25 int, @Col26 int, @Col27 int, @Col28 int, @Col29 int, @Col30 int, @Col31 int, @Col32 int
)
RETURNS binary(132) 
WITH EXECUTE AS CALLER
AS EXTERNAL NAME Obbish.UserDefinedFunctions.NullableIntsToBinary;

ソースコード

C#ソースはhttps://gist.github.com/SQLKiwi/64f320fe7fd802a68a3a644aa8b8af9fにあります

これを自分でコンパイルする場合は、ターゲットプロジェクトタイプとしてクラスライブラリ(.dll)を使用し、[安全でないコード許可する]ビルドオプションをオンにする必要があります。

複合ソリューション

最終的に上記で返されたバイナリデータのSpookyHashを計算する必要があるため、CLR関数内でSpookyHashを呼び出して16バイトハッシュを返すことができます。

列データ型が混在するテーブルに基づく実装例は、https://gist.github.com/SQLKiwi/6f82582a4ad1920c372fac118ec82460にあります。これには、Jon HannaのSpookilySharpから派生したSpooky Hashアルゴリズムの安全でないインラインバージョンと、Bob Jenkinsによる元のパブリックドメインCソースコードが含まれています。


7

INT列は正確にのサイズと一致する許容値の4つのバイトを持っていますBINARY(4)。言い換えると、BINARY(4)の可能な値はすべて、INT列の可能な値と一致します。そのため、INT列で許可されていない値がない限り、NULLを安全に置き換えることはできません。列がNULLかどうかは、個別にエンコードする必要があります。それは単にに収まらないBINARY(4)

これを行う1つの方法は、NULLビットマップを使用することです。次のコードを検討してください。

CAST(       
    CASE WHEN COL1 IS NOT NULL THEN 0 ELSE 1 END | 
    CASE WHEN COL2 IS NOT NULL THEN 0 ELSE 2 END | 
    CASE WHEN COL3 IS NOT NULL THEN 0 ELSE 4 END | 
    CASE WHEN COL4 IS NOT NULL THEN 0 ELSE 8 END | 
    CASE WHEN COL5 IS NOT NULL THEN 0 ELSE 16 END | 
    CASE WHEN COL6 IS NOT NULL THEN 0 ELSE 32 END | 
    CASE WHEN COL7 IS NOT NULL THEN 0 ELSE 64 END | 
    CASE WHEN COL8 IS NOT NULL THEN 0 ELSE 128 END
AS BINARY(1))

8列がNULLであるかどうかは、1バイトに収まります。これらの式を行間で比較して、同じ列がすべてNULLかどうかを確認できます。その追加情報により、NULLカラム値をNULL以外の値で安全に置き換えることができます。CAST(ISNULL(COL1, 0) AS BINARY(4))他のバリエーションISNULL(CAST(COL1 AS VARBINARY(4)), 0x)も可能ですが、最速であることがわかりました。

確実に何かを証明するのは難しいですが、次の詳細が最速であることがわかりました。

  • ほとんどの列値がNULLにならないことがわかっているため、ビットマップのNOT NULLに0を使用します
  • ビットごとまたはビットマップの追加の代わりに使用する
  • 変換されたバイナリ値ではなく、列の値がNULLかどうかを確認する

私のマシンでは、ベンチマークには約27.5 CPU秒かかります。残念ながら、NULLビットマップのステップには、その時間の約3分の1がかかります。これを行うためのより高速な方法があればいいでしょう。

完全なソリューションは次のとおりです。

SELECT
    CAST(ISNULL(COL1, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL2, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL3, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL4, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL5, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL6, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL7, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL8, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL9, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL10, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL11, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL12, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL13, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL14, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL15, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL16, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL17, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL18, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL19, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL20, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL21, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL22, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL23, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL24, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL25, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL26, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL27, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL28, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL29, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL30, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL31, 0) AS BINARY(4)) + 
    CAST(ISNULL(COL32, 0) AS BINARY(4)) + 
    CAST(       
        CASE WHEN COL1 IS NOT NULL THEN 0 ELSE 1 END | 
        CASE WHEN COL2 IS NOT NULL THEN 0 ELSE 2 END | 
        CASE WHEN COL3 IS NOT NULL THEN 0 ELSE 4 END | 
        CASE WHEN COL4 IS NOT NULL THEN 0 ELSE 8 END | 
        CASE WHEN COL5 IS NOT NULL THEN 0 ELSE 16 END | 
        CASE WHEN COL6 IS NOT NULL THEN 0 ELSE 32 END | 
        CASE WHEN COL7 IS NOT NULL THEN 0 ELSE 64 END | 
        CASE WHEN COL8 IS NOT NULL THEN 0 ELSE 128 END
    AS BINARY(1)) + 
    CAST(   
        CASE WHEN COL9  IS NOT NULL THEN 0 ELSE 1 END | 
        CASE WHEN COL10 IS NOT NULL THEN 0 ELSE 2 END | 
        CASE WHEN COL11 IS NOT NULL THEN 0 ELSE 4 END | 
        CASE WHEN COL12 IS NOT NULL THEN 0 ELSE 8 END | 
        CASE WHEN COL13 IS NOT NULL THEN 0 ELSE 16 END | 
        CASE WHEN COL14 IS NOT NULL THEN 0 ELSE 32 END | 
        CASE WHEN COL15 IS NOT NULL THEN 0 ELSE 64 END | 
        CASE WHEN COL16 IS NOT NULL THEN 0 ELSE 128 END
    AS BINARY(1)) + 
    CAST(   
        CASE WHEN COL17 IS NOT NULL THEN 0 ELSE 1 END | 
        CASE WHEN COL18 IS NOT NULL THEN 0 ELSE 2 END | 
        CASE WHEN COL19 IS NOT NULL THEN 0 ELSE 4 END | 
        CASE WHEN COL20 IS NOT NULL THEN 0 ELSE 8 END | 
        CASE WHEN COL21 IS NOT NULL THEN 0 ELSE 16 END | 
        CASE WHEN COL22 IS NOT NULL THEN 0 ELSE 32 END | 
        CASE WHEN COL23 IS NOT NULL THEN 0 ELSE 64 END | 
        CASE WHEN COL24 IS NOT NULL THEN 0 ELSE 128 END
    AS BINARY(1)) + 
    CAST(   
        CASE WHEN COL25 IS NOT NULL THEN 0 ELSE 1 END | 
        CASE WHEN COL26 IS NOT NULL THEN 0 ELSE 2 END | 
        CASE WHEN COL27 IS NOT NULL THEN 0 ELSE 4 END | 
        CASE WHEN COL28 IS NOT NULL THEN 0 ELSE 8 END | 
        CASE WHEN COL29 IS NOT NULL THEN 0 ELSE 16 END | 
        CASE WHEN COL30 IS NOT NULL THEN 0 ELSE 32 END | 
        CASE WHEN COL31 IS NOT NULL THEN 0 ELSE 64 END | 
        CASE WHEN COL32 IS NOT NULL THEN 0 ELSE 128 END
    AS BINARY(1))
FROM dbo.TABLE_OF_32_INTS
OPTION (MAXDOP 1);

5

私のテストでは、concat_wsはnullビットマップソリューション(26秒)よりも少し高速(18秒)でした。シャッフルするデータが増えるため、他の場所でパフォーマンスが低下する可能性があります。これを文字列と混在させる場合は、区切り文字を賢明に選択する必要があります。

select @dummy = cast(concat_ws('|',
         isnull(cast(T.COL1  as varchar(11)), ''),
         isnull(cast(T.COL2  as varchar(11)), ''),
         isnull(cast(T.COL3  as varchar(11)), ''),
         isnull(cast(T.COL4  as varchar(11)), ''),
         isnull(cast(T.COL5  as varchar(11)), ''),
         isnull(cast(T.COL6  as varchar(11)), ''),
         isnull(cast(T.COL7  as varchar(11)), ''),
         isnull(cast(T.COL8  as varchar(11)), ''),
         isnull(cast(T.COL9  as varchar(11)), ''),
         isnull(cast(T.COL10 as varchar(11)), ''),
         isnull(cast(T.COL11 as varchar(11)), ''),
         isnull(cast(T.COL12 as varchar(11)), ''),
         isnull(cast(T.COL13 as varchar(11)), ''),
         isnull(cast(T.COL14 as varchar(11)), ''),
         isnull(cast(T.COL15 as varchar(11)), ''),
         isnull(cast(T.COL16 as varchar(11)), ''),
         isnull(cast(T.COL17 as varchar(11)), ''),
         isnull(cast(T.COL18 as varchar(11)), ''),
         isnull(cast(T.COL19 as varchar(11)), ''),
         isnull(cast(T.COL20 as varchar(11)), ''),
         isnull(cast(T.COL21 as varchar(11)), ''),
         isnull(cast(T.COL22 as varchar(11)), ''),
         isnull(cast(T.COL23 as varchar(11)), ''),
         isnull(cast(T.COL24 as varchar(11)), ''),
         isnull(cast(T.COL25 as varchar(11)), ''),
         isnull(cast(T.COL26 as varchar(11)), ''),
         isnull(cast(T.COL27 as varchar(11)), ''),
         isnull(cast(T.COL28 as varchar(11)), ''),
         isnull(cast(T.COL29 as varchar(11)), ''),
         isnull(cast(T.COL30 as varchar(11)), ''),
         isnull(cast(T.COL31 as varchar(11)), ''),
         isnull(cast(T.COL32 as varchar(11)), ''))
       as varbinary(8000))
from dbo.TABLE_OF_32_INTS as T
option (maxdop 1)

2
これをありがとう。私にとっても高速ですが、より長いバイナリ文字列を生成するという欠点があります(サンプルデータの場合は132文字に対して191文字)。私たちは間違いなくそれを検討します。
ジョーオブビッシュ

-1

特定のintを保存しないことを事前に確認できる場合は、次のよう-2,147,483,648にできます。

 SELECT @dummy = 
        coalesce(CAST(COL1 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL2 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL3 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL4 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL5 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL6 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL7 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL8 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL9 AS BINARY(4)),  0x80000000) + 
        coalesce(CAST(COL10 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL11 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL12 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL13 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL14 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL15 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL16 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL17 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL18 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL19 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL20 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL21 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL22 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL23 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL24 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL25 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL26 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL27 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL28 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL29 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL30 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL31 AS BINARY(4)), 0x80000000) + 
        coalesce(CAST(COL32 AS BINARY(4)), 0x80000000) 
    FROM dbo.TABLE_OF_32_INTS

答えてくれてありがとう。INT列に許可されるすべての値が可能です。
ジョーオブビッシュ
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.