/ /

$convert (표현식 연산자)

정의

$convert: 값을 지정된 유형으로 변환합니다.

호환성

다음 환경에서 호스팅되는 배포에 $convert 사용할 수 있습니다.

MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스

MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전

구문

버전 8.3에서 변경되었습니다.

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         base: <expression>,       // new in 8.3
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

$convert 은 다음 필드가 있는 문서를 가져옵니다.

필드	필요성	설명
`input`	필수 사항	인수는 유효한 표현식 이면 무엇이든 될 수 있습니다. 표현식에 대한 자세한 내용은 표현식을 참조하세요 . MongoDB 8.1부터는 `input` 필드 다음 유형 중 하나로 설정하다 하면 `to` 필드 `binData` 로 설정하다 수 있습니다. `int` `long` `double` MongoDB 8.3부터는 `input` 필드 숫자 값의 `array` 인 경우 `to` 필드 `binData` 로 설정하다 수도 있습니다. 예제는 숫자 값 배열을 binData로 변환을 참조하세요. MongoDB 값을 `binData`로 변환할 때 이러한 숫자 유형도 입력으로 지원합니다.
`to`	필수 사항	`input` 표현식을 변환할 유형을 지정합니다. `to`를 다음 값 중 하나로 설정할 수 있습니다. 대상 유형에 대한 문자열 또는 숫자 식별자입니다. `to.type`을 참조하세요. `to.type` 및 `to.subtype` 필드를 포함하는 객체 . 이 형식을 사용하여 `binData` 로 변환하고 `binData` 하위 유형을 지정합니다.
`to.type`	`to`를 객체로 지정하는 경우에 필요합니다.	인수는 숫자 또는 string 식별자로 해석되는 모든 유효한 표현식 일 수 있습니다. 사용 가능한 식별자에 대한 자세한 내용은 유형 식별자를 참조하십시오.
`to.subtype`	옵션	`to.type` 이 `binData`인 경우 `to.subtype` 은 변환할 binData 하위 유형을 지정합니다. 유효한 값은 바이너리 하위 유형을 참조하세요. 기본값: 0 (일반 바이너리 하위 유형).
`byteOrder`	옵션	`binData` 와 숫자 유형 간의 변환에 대한 빅 또는 리틀 엔디안 바이트 순서를 지정합니다. 지정하지 않으면 기본값 은 리틀 엔디안 바이트 순서입니다.
`base`	옵션	문자열과 숫자 유형 간의 변환을 위한 정수입니다. `null`인 경우 `$convert` 는 기본을 생략한 것처럼 작동합니다. 지정된 경우 MongoDB 문자열과 숫자 유형 `int`, `long`, `double`, `decimal` 간을 변환할 때 선택한 기준의 값을 해석합니다. 다른 변환의 경우 MongoDB `base` 값의 유효성을 검사하지만 그렇지 않으면 무시합니다. 기본값은 `2`, `8`, `10` 또는 `16`여야 합니다. 버전 8.3에 추가 되었습니다.
`format`	`binData` 및 문자열(으)로 변환하거나 그 반대로 변환할 때 필요합니다.	`binData` 와 문자열 간의 변환 형식을 지정합니다. `base64` `base64url` `utf8` `hex` `uuid` `format`이 `uuid`인 경우 `to.subtype`은 `4`여야 합니다.
`onError`	옵션	변환 중 오류가 발생했을 때 반환할 값입니다. 여기에는 지원되지 않는 유형 변환이 포함됩니다. 인수는 유효한 모든 표현식일 수 있습니다. 지정하지 않으면 오류 발생 시 작업에 오류가 발생하고 중지됩니다.
`onNull`	옵션	`input`이 null이거나 누락된 경우 반환할 값입니다. 인수는 유효한 표현식일 수 있습니다. `$convert` 지정하지 않으면 는 `input` 이 null이거나 누락된 경우 null을 반환합니다.

$convert 이외에도 MongoDB는 기본 'onError'와 'onNull' 동작이 허용되는 경우 다음과 같은 집계 연산자를 축약형으로 제공합니다.

유형 식별자

to.type 필드는 다음 숫자 및 string 식별자를 허용합니다.

문자열 식별자	숫자 식별자	참고 사항
"double"	1	참조: double로 변환.
"문자열"	2	string 변환을 참조하십시오.
"객체"	3	객체로 변환을 참조하세요.
"배열"	4	배열로 변환을 참조하세요.
"binData"	5	참조: BinData로 변환.
"objectId"	7	ObjectId로 변환을 참조하세요.
"bool"	8	불리언으로 변환을 참조하세요.
'날짜'	9	날짜로 변환을 참조하세요.
"in"	16	정수로 변환을 참조하세요.
"long"	18	길게 변환을 참조하십시오.
"십진수"	19	10진수로 변환을 참조하세요.

바이너리 하위 유형

다음 표에는 to.subtype 필드에 대한 유효한 값이 나열되어 있습니다.

번호	설명
0	일반 바이너리 하위 유형
1	함수 데이터
2	바이너리(이전)
3	UUID(이전)
4	UUID
5	MD5
6	암호화된 BSON 값
7	압축된 Time Series 데이터 버전 5.2에 추가되었습니다.
8	키나 시크릿과 같은 민감한 데이터. MongoDB는 하위 유형이 8인 바이너리 데이터에 대한 리터럴 값을 기록하지 않습니다. 대신 자리 표시자 값 `###` 을 기록합니다.
9	벡터 데이터는 동일한 유형의 숫자가 밀집되어 있는 배열입니다.
128	사용자 지정 데이터

행동

다음 섹션에서는 값을 다른 유형으로 변환하는 방법을 설명합니다.

BinData로 변환

MongoDB 8.1부터는 input 필드 다음 유형 중 하나로 설정하다 하면 to 필드 binData 로 설정하다 수 있습니다.

int
long
double

MongoDB 8.1부터 $convert 는 서로 다른 binData 하위 유형 간에 변환을 시도할 때 오류를 반환합니다. MongoDB 8.0에서 $convert 는 원래 값과 원래 하위 유형을 반환합니다: 변환이 수행되지 않습니다. 8.0 이전의 MongoDB 버전에는 binData 변환 기능이 없습니다.

숫자 유형에서 `binData`(으)로 변환합니다.

숫자 유형을 binData로 변환하는 경우:

int 은(는) 4바이트 binData이(가) 됩니다.
long 은(는) 8바이트 binData이(가) 됩니다.
double 은(는) 8바이트 binData이(가) 됩니다.

숫자 출력의 byteOrder 기본값은 "little", 즉 가장 덜 중요한 바이트를 먼저 배치합니다. 반대로 'big'은 최상위 바이트를 먼저 배치합니다.

long 을 binData로 변환합니다:

입력:

db.t.insertOne( { a: Long(42) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
      }
    },
  }
}
])

출력:

[
  {
    convertedBD: Binary.createFromBase64('KgAAAAAAAAA=', 0)
  }
]

빅 엔디안 바이트 순서를 사용하여 long 를 binData 로 변환합니다.

입력:

db.t.insertOne( { a: Long(42) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
           byteOrder: "big",
        }
      },
    }
  }
])

출력:

[
  {
    convertedBD: Binary.createFromBase64('AAAAAAAAACo=', 0),
  }
]

double 을 binData로 변환합니다:

입력:

db.t.insertOne( { a: Double(42.0) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
        }
      },
    }
  }
])

출력:

[
  {
    convertedBD: Binary.createFromBase64('AAAAAAAARUA=', 0)
  }
]

int 을 binData로 변환합니다:

입력:

db.t.insertOne( { a: 42 } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
        }
      },
    }
  }
])

출력:

[
  {
    convertedBD: Binary.createFromBase64('KgAAAA==', 0)
  }
]

숫자 값 배열 binData로 변환합니다.

이 예시 $convert 이(가) 서로 다른 유형의 숫자 값이 포함된 배열을 binData(으)로 변환하는 방법을 보여 줍니다.

입력:

db.t.insertMany([
    // Empty array
    { a: [ ] },
    // Bool array
    { a: [
            false, true,  true,  true,
            true,  true,  true,  true,
            false, false, false, false,
            false, true,  true,  true
         ]
    },
    // Int array 
    { a: [NumberInt(0), NumberInt(1), NumberInt(0), NumberInt(10)] },
    
    // Double array 
    { a: [ Double(0.0), Double(1.0), Double(0.0), Double(1.0), Double(3.14) ] },
])

db.t.aggregate([
    {
      $project: {
        _id: 0,
        original: "$a",
        convertedVector: {
          $convert: {
            input: "$a",
            to: { type: "binData" } 
          }
        }
      }
    }
])

출력:

[
  {
    original: [],
    convertedVector: Binary.fromPackedBits(new Uint8Array([]))
  },
  {
    original: [
      false, true,  true,  true,
      true,  true,  true,  true,
      false, false, false, false,
      false, true,  true,  true
    ],
    convertedVector: Binary.fromPackedBits(new Uint8Array([ 127, 7 ]))
  },
  {
    original: [ 0, 1, 0, 10 ],
    convertedVector: Binary.fromInt8Array(new Int8Array([ 0, 1, 0, 10 ]))
  },
  {
    original: [ 0, 1, 0, 1, 3.14 ],
    convertedVector: Binary.fromFloat32Array(new Float32Array([ 0, 1, 0, 1, 3.140000104904175 ]))
  }
]

문자열에서 BinData로 변환

MongoDB binData 와 문자열 간의 변환도 지원합니다.

다음 예제에서는 문자열을 binData로 변환하는 방법을 보여 줍니다.

예시

결과

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: "binData",
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64"
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Input is not a valid base64
string.

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "base64"
}

Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convert
with no onError value: Input is not a valid base64 string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

UUID('867dee52-c331-484e-92d1-c56479b8e67e')

{
   input: "äöäöä",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

Failed to parse BinData 'äöäöä' in $convert with no onError
value: Input is not a valid UUID string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: { type: "binData" },
   format: "uuid"
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Only the UUID subtype (4)
is allowed with the 'uuid' format.

참고

배열로 변환

버전 8.3에 추가 되었습니다.

다음 표에는 배열 로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
BinData	숫자 값의 배열 반환합니다. 배열 요소의 숫자 유형은 binData 형식에 따라 달라집니다.
문자열	string 내의 내용에 해당하는 배열 반환합니다. The string must contain characters that represent a valid JSON 배열.
Null 또는 누락	null을 반환합니다.

다음 표에는 문자열을 배열 로 변환하는 몇 가지 예가 나와 있습니다.

예시

결과

{ input: "[1, 2, 3]", to: "array" }

[ 1, 2, 3 ]

{ input: '["a", "b", "c"]', to: "array" }

[ 'a', 'b', 'c' ]

{ input: "[]", to: "array" }

[ ]

{ input: "{}", to: "array" }

오류: 입력이 예상 유형 ' 배열'과 일치하지 않습니다.

{ input: 123, to: "array" }

오류: onError 값이 없는 $convert에서 int에서 배열 로의 변환이 지원되지 않습니다.

{ input: "123", to: "array" }

오류: 입력이 유효한 JSON 나타내지 않음: 예기치 않은 독립형 값

{ input: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]", to:
"array" }

[ { '$oid': '507f1f77bcf86cd799439011' } ]

{ input: "[1, 2, 3]", to: "array", format: "base64url" }

[ 1, 2, 3 ]

{ input: "asdf", to: "array", onError: "on error!" }

'on error!'

{ input: null, to: "array", onNull: "on null!" }

'on null!'

binData를 배열로 변환

이 예시 $convert 이(가) 서로 다른 형식의 binData 을(를) 해당 유형의 값이 포함된 배열로 변환하는 방법을 보여 줍니다.

input:

db.t.insertMany([
  // Empty PACKED_BIT vector converts to empty array
  { v: BinData(9, "EAA=") },
  // PACKED_BIT vector converts to bool array
  { v: BinData(9, "EAB/Bw==") },
  // INT8 vector converts to int array
  { v: BinData(9, "AwAAAQ==") },
  // FLOAT32 vector converts to double array
  { v: BinData(9, "JwCamZk+") },
  // FLOAT32 vector with special values converts to [-Infinity, 0, Infinity]
  { v: BinData(9, "JwAAAID/AAAAAAAAgH8=") }
])

db.t.aggregate([
  {
    $project: {
      _id: 0,
      original: "$v",
      asArray: {
        $convert: {
          input: "$v",
          to: { type: "array" }
        }
      }
    }
  }
])

출력:

[
  { original: Binary.fromPackedBits(new Uint8Array([])), asArray: [] },
  {
    original: Binary.fromPackedBits(new Uint8Array([ 127, 7 ])),
    asArray: [
      false, true,  true,  true,
      true,  true,  true,  true,
      false, false, false, false,
      false, true,  true,  true
    ]
  },
  {
    original: Binary.fromInt8Array(new Int8Array([ 0, 1 ])),
    asArray: [ 0, 1 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ 0.30000001192092896 ])),
    asArray: [ 0.30000001192092896 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ -Infinity, 0, Infinity ])),
    asArray: [ -Infinity, 0, Infinity ]
  }
]

객체로 변환

버전 8.3에 추가 되었습니다.

다음 표에는 input 로 변환할 수 있는 객체 유형이 나열되어 있습니다.

입력 유형	행동
문자열	string 내의 내용에 해당하는 document를 반환합니다. 문자열에는 유효한 JSON 객체 나타내는 문자가 포함되어야 합니다.
Null 또는 누락	null을 반환합니다.

다음 표에는 객체 로 변환하는 몇 가지 예가 나와 있습니다.

예시

결과

{ input: "{\"a\": 1, \"b\": 2}", to: "object" }

{ a: 1, b: 2 }

{ input: "{}", to: "object" }

{ }

{ input: "[]", to: "object" }

오류: 입력이 예상 유형 ' 객체'와 일치하지 않습니다.

{ input: "123", to: "object" }

오류: 입력이 유효한 JSON 나타내지 않음: 예기치 않은 독립형 값

{ input: "{\"nam\\u0000e\": \"foo\"}", to: "object" }

오류: 입력이 유효한 JSON 나타내지 않음: 잘못 포함된 null 바이트

{ input: "{\"name\": \"fo\\u0000o\"}", to: "object" }

{ name: 'fox00o' }

{ input: "{\"a\": 1, \"b\": 2, \"a\": 3}", to: "object" }

{ a: 3, b: 2 }

{ input: "{\"foo\": null}", to: "object" }

{ foo: null }

{ input: "{\"foo\": false}", to: "object" }

{ foo: false }

{ input: "{\"__proto__\": {\"foo\": null}}", to: "object" }

{ ['__proto__']: { foo: null } }

{ input: "{\"foo\": \"NaN\"}", to: "object" }

{ foo: 'NaN' }

{ input: "{\"foo\": 123}", to: "object" }

{ foo: 123 }

{ input: "{\"foo\": 4294967296}", to: "object" }

{ foo: Long('4294967296') }

{ input: "{\"foo\": 1.123123}", to: "object" }

{ foo: 1.123123 }

{ input: "{\"foo\": 1.2e+3}", to: "object" }

{ foo: 1200 }

{ input: "{\"largePos\": 18446744073709551615}", to: "object" }

{ largePos: 18446744073709552000 }

{ input: "{\"largeNeg\": -18446744073709551615}", to: "object" }

{ largeNeg: -18446744073709552000 }

{ input: null, to: "object" }

null

{
   input: "{\"objectId\": \"507f1f77bcf86cd799439011\",
   \"uuid\": \"3b241101-e2bb-4255-8caf-4136c566a962\",
   \"date\": \"2018-03-27T16:58:51.538Z\", \"regex\":
   \"/^ABC/i\", \"js\": \"function (s) {return s +
   \\\"foo\\\";}\", \"timestamp\": \"Timestamp(1565545664,
   1)\", \"arr\": [1, 2, 3]}", to: "object"
}

{

objectId: '507f1f77bcf86cd799439011',
uuid: '3b241101-e2bb-4255-8caf-4136c566a962',
date: '2018-03-27T16:58:51.538Z',
regex: '/^ABC/i',
js: 'function (s) {return s + "foo";}',
timestamp: 'Timestamp(1565545664, 1)',
arr: [ 1, 2, 3 ]

}

부울로 변환

다음 표에는 더블로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
배열	true를 반환합니다
이진 데이터	true를 반환합니다
부울	아니요. 부울 값을 반환합니다.
코드	true를 반환합니다
날짜	true를 반환합니다
10진수	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
Integer	Returns true if not zero Return false if zero
JavaScript	true를 반환합니다
Long	Returns true if not zero Return false if zero
최대 키	true를 반환합니다
최소 키	true를 반환합니다
Null	`onNull` 옵션에 지정된 값을 반환합니다. 기본적으로 null을 반환합니다.
객체	true를 반환합니다
ObjectId	true를 반환합니다
정규 표현식	true를 반환합니다
문자열	true를 반환합니다
타임스탬프	true를 반환합니다

MongoDB의 데이터 유형에 대해 자세히 알아보려면 BSON types를 참조하세요.

다음 표에는 더블로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "bool" }

true

{ input: false, to: "bool" }

거짓

{ input: 1.99999, to: "bool" }

true

{ input: Decimal128( "5" ), to: "bool" }

true

{ input: Decimal128( "0" ), to: "bool" }

거짓

{ input: 100, to: "bool" }

true

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "bool"
}

true

{ input: "hello", to: "bool" }

true

{ input: "false", to: "bool" }

true

{ input: "", to: "bool" }

true

{ input: null, to: "bool" }

null

정수로 변환

다음 표에는 정수로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `0` for `false`. Returns `1` for `true`.
BinData	`binData` 값을 정수로 반환합니다. `binData` 은(는) 2의 부호 있는 보수 부호 있는 정수로 해석됩니다. `binData` 값의 바이트 수는 `1`, `2` 또는 `4`여야 합니다. `input` 의 길이가 예기치 않은 경우 오류가 발생합니다. `$convert.onError`를 구성하여 이 동작을 제어할 수 있습니다.
Double	잘린 값을 반환합니다. 잘린 double 값은 정수의 최소값과 최대값 내에 속해야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 double 값은 변환할 수 없습니다.
10진수	잘린 값을 반환합니다. 잘린 10진수 값은 정수의 허용 범위 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 소숫값은 변환할 수 없습니다.
Integer	아니요. 정수 값을 반환합니다.
Long	긴 값을 정수로 반환합니다. long 값은 정수의 최소값과 최대값 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 Long 값은 변환할 수 없습니다.
문자열	문자열의 숫자 값을 정수로 반환합니다. If you omit `base` or set to `null`, the string value must be a valid base ₁₀ integer and fall within the minimum and maximum value for an integer. `base`을 지정하는 경우 문자열에는 해당 기준에서 유효한 숫자만 포함되어야 합니다. `"0x"`와 같은 접두사는 허용되지 않습니다. 결과 정수는 정수의 최소값과 최대값 내에 있어야 합니다.

다음 표에는 정수로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "int" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

{ input: Decimal128( "5.5000" ), to: "int" }

{
   input: Decimal128( "9223372036000.000" ),
   to: "int"
}

오류

{ input: Long( "5000" ), to: "int" }

5000

{ input: Long( "922337203600" ), to: "int" }

오류

{ input: "-2", to: "int" }

-2

{ input: "2.5", to: "int" }

오류

{ input: null, to: "int" }

null

{
   input: Binary(Buffer.from("00100000", "hex"), 0),
   to: "int",
   byteOrder: "big",
}

1048576

{
   input: Binary(Buffer.from("FFFFE796", "hex"), 0),
   to: "int",
}

-1763180545

{
   input: Binary(Buffer.from("001000000000000", "hex"), 0),
   to: "int",
   byteOrder: "big",
}

오류: 잘못된 길이로 인해 BinData를 변환하지 못했습니다: 7

10진수로 변환

다음 표에는 10진수로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	double 값을 10진수로 반환합니다.
10진수	아니요. 소수를 반환합니다.
Integer	int 값을 10진수로 반환합니다.
Long	Long 값을 10진수로 반환합니다.
문자열	문자열의 숫자 값을 10진수로 반환합니다. `base` 을 생략하거나 `null`로 설정하다 경우 string 값은 유효한 기본 ₁₀ 소수점이어야 하며 소수점의 최소값과 최대값 내에 속해야 합니다. `base`을 지정하는 경우 문자열에는 해당 기준에서 유효한 숫자만 포함되어야 합니다. `"0x"`와 같은 접두사는 허용되지 않습니다. 결과 소수점은 소수점의 최소값과 최대값 내에 있어야 합니다.
날짜	날짜 값에 해당하는 epoch 이후의 밀리초 수를 반환합니다.

다음 표에는 10진수로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "decimal" }

Decimal128("1")

{ input: false, to: "decimal" }

Decimal128("0")

{ input: 2.5, to: "decimal" }

Decimal128( "2.50000000000000" )

{ input: Int32( 5 ), to: "decimal" }

Decimal128("5")

{ input: Long( 10000 ), to: "decimal" }

Decimal128("10000")

{ input: "-5.5", to: "decimal" }

Decimal128("-5.5")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "decimal"
}

Decimal128("1522039108044")

double로 변환

다음 표에는 double로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
BinData	`binData` 값을 double로 반환합니다. `binData` 은(는) IEEE 754 단정밀도 또는 배정밀도 부동 점 으로 해석됩니다. `binData` 값의 바이트 수는 `4` 또는 `8`여야 합니다. `input` 의 길이가 예기치 않은 경우 오류가 발생합니다. `$convert.onError`를 구성하여 이 동작을 제어할 수 있습니다.
Double	아니요. double 값을 반환합니다.
10진수	10진수 값을 double로 반환합니다. 10진수 값은 double의 최소값과 최대값 내에 속해야 합니다. 값이 최소 double 값보다 작거나 최대 double 값보다 큰 10진수 값은 변환할 수 없습니다.
Integer	int 값을 double로 반환합니다.
Long	긴 값을 double로 반환합니다.
문자열	문자열의 숫자 값을 double로 반환합니다. `base` 을 생략하거나 `null`로 설정하다 경우 string 값은 유효한 기본 ₁₀ double이어야 하며 double의 최소값과 최대값 내에 속해야 합니다. `base`을 지정하는 경우 문자열에는 해당 기준에서 유효한 숫자만 포함되어야 합니다. `"0x"`와 같은 접두사는 허용되지 않습니다. 결과 더블은 더블의 최소값과 최대값 내에 있어야 합니다.
날짜	날짜 값에 해당하는 epoch 이후의 밀리초 수를 반환합니다.

다음 표에는 double로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "double" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

2.5

{ input: Int32( 5 ), to: "double" }

{ input: Long( "10000" ), to: "double" }

10000

{ input: "-5.5", to: "double" }

-5.5

{ input: "5e10", to: "double" }

50000000000

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "double"
}

1522039108044

{
   input: Binary(Buffer.from("04CCCCCD", "hex"), 0),
   to: "double",
   byteOrder: "big",
}

4.814824932714571e-36

{
   input: Binary(Buffer.from("0000", "hex"), 0),
   to: "double",
   byteOrder: "big",
}

오류: 잘못된 길이로 인해 binData를 변환하지 못했습니다: 2

비정규 숫자

MongoDB 8.3부터 서버 표현 가능한 모든 double 정밀도 부동 점 숫자의 전체 범위 구문 분석할 수 있습니다. 여기에는 최상위 숫자 앞에 0이 있고 지수가 가능한 가장 작은 값을 갖는 비정규 숫자 가 포함됩니다. 자세한 내용은 비정규 숫자를 참조하세요.

이전 버전의 MongoDB 에서는 이러한 숫자를 구문 분석하려고 하면 서버 오류를 반환합니다. 다음 예시 에서는 MongoDB 8.3 이전 버전에서 오류를 발생시킵니다.

db.t.insertOne( { v: "7.08263e-317" } )
db.t.aggregate([
  {
    $project: {
      converted: {
        $convert: { input: "$v", to: "double" },
      }
    }
   }
])

이 예시 다음과 유사한 오류로 인해 실패합니다.

MongoServerError[ConversionFailure]: Executor error during aggregate command on namespace: test.t ::
caused by :: Failed to parse number '7.08263e-317' in $convert with no onError value: Out of range

길게 변환

다음 표에는 로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `0` for `false`. Returns `1` for `true`.
BinData	`binData` 값을 long으로 반환합니다. `binData` 은(는) 2의 부호 있는 보수 부호 있는 정수로 해석됩니다. `binData` 값의 바이트 수는 `1`, `2`, `4` 또는 `8`여야 합니다. `input` 의 길이가 예기치 않은 경우 오류가 발생합니다. `$convert.onError`를 구성하여 이 동작을 제어할 수 있습니다.
Double	잘린 값을 반환합니다. 잘린 double 값은 정수의 최소값과 최대값 내에 속해야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 double 값은 변환할 수 없습니다.
10진수	잘린 값을 반환합니다. 잘린 10진수 값은 정수의 허용 범위 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 더블 값은 변환할 수 없습니다.
Integer	int 값을 길이로 반환합니다.
Long	아니요. 긴 값을 반환합니다.
문자열	문자열의 숫자 값을 반환합니다. `base` 을 생략하거나 `null`로 설정하다 경우 string 값은 유효한 기본 길이 ₁₀ 이어야 하며 길이의 최소값과 최대값 내에 속해야 합니다. `base`을 지정하는 경우 문자열에는 해당 기준에서 유효한 숫자만 포함되어야 합니다. `"0x"`와 같은 접두사는 허용되지 않습니다. 결과 long은 long의 최소값과 최대값 내에 있어야 합니다.
날짜	Date를 epoch 이후의 밀리초 수로 변환합니다.

다음 표에는 더블로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Long("0")

{ input: 2.5, to: "long"  }

Long("2")

{ input: Decimal128( "5.5000" ), to: "long" }

Long("5")

{
   input: Decimal128( "9223372036854775808.0" ),
   to: "long"
}

오류

{ input: Int32( 8 ), to: "long" }

Long("8")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "long"
}

Long("1522039108044")

{ input: "-2", to: "long" }

Long("-2")

{ input: "2.5", to: "long" }

오류

{ input: null, to: "long" }

null

{
   input: Binary(Buffer.from("001000000", "hex"), 0),
   to: "long",
   byteOrder: "big",
}

Long("1048576")

날짜로 변환

다음 표에는 날짜로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
Double	잘린 double 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
10진수	잘린 10진수 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
Long	long 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
문자열	날짜 문자열에 해당하는 날짜를 반환합니다. 문자열은 다음과 같이 유효한 날짜 문자열이어야 합니다: "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	ObjectId의 타임스탬프에 해당하는 날짜를 반환합니다.
타임스탬프	타임스탬프에 해당하는 날짜를 반환합니다.

다음 표에는 날짜로의 몇 가지 변환 예가 나열되어 있습니다.

예시

결과

{
   input: 120000000000.5,
   to: "date"
}

ISODate("1973-10-20T21:20:00.000Z")

{
   input: Decimal128( "1253372036000.50" ),
   to: "date"
}

ISODate("2009-09-19T14:53:56.000Z")

{
   input: Long( "1100000000000" ),
   to: "date
}

ISODate("2004-11-09T11:33:20.000Z")

{
   input:  Long( "-1100000000000" ),
   to: "date"
}

ISODate("1935-02-22T12:26:40.000Z")

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "date"
}

ISODate("2018-03-27T04:08:58.000Z")

{ input:  "2018-03-03", to: "date" }

ISODate("2018-03-03T00:00:00.000Z")

{
   input: "2018-03-20 11:00:06 +0500",
   to: "date"
}

ISODate("2018-03-20T06:00:06.000Z")

{ input: "Friday", to: "date" }

오류

{
   input: Timestamp( { t: 1637688118, i: 1 } ),
   to: "date"
}

ISODate("2021-11-23T17:21:58.000Z")

ObjectId로 변환

다음 표에는 ObjectId로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
문자열	길이 24의 16진수 문자열에 대한 ObjectId를 반환합니다. 길이가 24인 16진수 문자열이 아닌 문자열 값은 변환할 수 없습니다.

다음 표에는 날짜로의 몇 가지 변환 예가 나열되어 있습니다.

예시

결과

{
   input: "5ab9cbfa31c2ab715d42129e",
   to: "objectId"
}

ObjectId("5ab9cbfa31c2ab715d42129e")

{
   input: "5ab9cbfa31c2ab715d42129",
   to: "objectId"
}

오류

문자열로 변환

다음 표에는 문자열로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
배열	`Array` 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.
BinData	`BinData` 가 UUID인 경우 UUID를 문자열로 반환합니다. 그렇지 않으면 기본64 인코딩된 string 값을 반환합니다.
부울	불리언 값을 문자열로 반환합니다.
날짜	`Date` 를 문자열로 반환합니다.
10진수	`Decimal` 값을 문자열로 반환합니다.
Double	`Double` 값을 문자열로 반환합니다.
Integer	`Integer` 값을 문자열로 반환합니다.
Long	`Long` 값을 문자열로 반환합니다.
최대 키	`MaxKey` 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.
최소 키	`MinKey` 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.
객체	객체 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.
ObjectId	`ObjectId` 값을 16진수 문자열로 반환합니다.
정규 표현식	`Regular Expression` 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.
문자열	작동하지 않습니다. string 값을 반환합니다.
타임스탬프	`Timestamp` 를 문자열로 반환합니다. 버전 8.3에 추가 되었습니다.

참고

base 을 지정하고 input 이 숫자 유형인 경우 $convert 는 해당 밑수로 사용되는 정수 값의 string 표현을 반환합니다. 문자열의 기본 변환은 정수 값에 대해서만 지원되며, 그렇지 않으면 $convert 은 onError을 지정하지 않는 한 변환 오류를 반환합니다.

다음 표에는 문자열로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "string" }

"true"

{ input: false, to: "string" }

"false"

{ input: 2.5, to: "string" }

"2.5"

{ input: Int32( 2 ), to: "string" }

"2"

{ input:  Long( 1000 ), to: "string" }

"1000"

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "string"
}

"5ab9c3da31c2ab715d421285"

{
   input:  ISODate( "2018-03-27T16:58:51.538Z" ),
   to: "string"
}

"2018-03-27T16:58:51.538Z"

{
   input: BinData(4, "hn3f"),
   to: "string",
   format: "base64"
}

'hn3f'

{
   input: 10.5,
   to: "string",
   base: 2,
   onError: "invalid"
}

"invalid"

예시

기본 변환 예시

자리 표시자 document 사용하여 examples 컬렉션 만듭니다.

db.examples.insertOne({ _id: 1 })

다음 예시 서로 다른 진법을 사용하여 숫자와 문자열을 변환합니다.

db.examples.aggregate([
  {
    $project: {
      _id: 0,
      bin:        { $convert: { input: 10,    to: "string", base: 2  } },
      hex:        { $convert: { input: 10,    to: "string", base: 16 } },
      intFromBin: { $convert: { input: "1010", to: "int",   base: 2  } },
      intFromHex: { $convert: { input: "A",    to: "int",   base: 16 } }
    }
  }
])

이 작업은 다음 document 반환합니다.

{
  bin: "1010",
  hex: "A",
  intFromBin: 10,
  intFromHex: 10
}

유형 변환 예시

다음 문서를 사용하여 컬렉션 orders를 생성합니다.

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

orders 컬렉션에서의 다음 집계 연산은 price를 10진수로 변환합니다.

// Define stage to add convertedPrice and convertedQty fields with
//    the converted price and qty values.
// If price or qty values are missing, the conversion returns a
//    value of decimal value or int value of 0.
// If price or qty values cannot be converted, the conversion returns
//    a string
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $convert:
         {
            input: "$price",
            to: "decimal",
            onError: "Error",
            onNull: Decimal128("0")
         } },
      convertedQty: { $convert:
         {
            input: "$qty",
            to: "int",
            onError:{ $concat:
               [
                  "Could not convert ",
                  { $toString:"$qty" },
                  " to type integer."
               ]
            },
         onNull: Int32("0")
      } },
   }
};
totalPriceCalculationStage = {
   $project: { totalPrice: {
     $switch: {
        branches: [
          { case:
             { $eq: [ { $type: "$convertedPrice" }, "string" ] },
             then: "NaN"
          },
          { case:
             { $eq: [ { $type: "$convertedQty" }, "string" ] },
             then: "NaN"
          },
        ],
        default: { $multiply: [ "$convertedPrice", "$convertedQty" ] }
     }
} } };
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
])

이 작업은 다음 문서를 반환합니다.

{ _id: 1, totalPrice: Decimal128("50") },
{ _id: 2, totalPrice: Decimal128("200.0") },
{ _id: 3, totalPrice: Decimal128("9.98") },
{ _id: 4, totalPrice: Decimal128("0") },
{ _id: 5, totalPrice: 'NaN' }

참고

이 예시에서는 mongosh를 사용합니다. 레거시 mongo 셸에서는 기본 유형이 다릅니다.

자세히 알아보기

다음을 사용하여 값을 배열 로 변환합니다. $toArray
다음을 사용하여 문자열을 객체 로 변환합니다. $toObject
다음을 사용하여 값을 부울로 변환합니다. $toBool
다음을 사용하여 값을 정수로 변환합니다. $toInt
다음을 사용하여 값을 소수로 변환합니다. $toDecimal
다음을 사용하여 값을 double 변환합니다. $toDouble
다음을 사용하여 값을 long으로 변환합니다. $toLong
다음을 사용하여 값을 날짜로 변환합니다. $toDate
다음을 사용하여 값을 ObjectId로 변환합니다. $toObjectId
다음을 사용하여 값을 문자열로 변환합니다. $toString
다음을 사용하여 날짜 문자열을 날짜 객체 로 변환합니다. $dateFromString
다음을 사용하여 날짜 객체 문자열로 변환합니다. $dateToString

돌아가기

$cond

$cos

정의

호환성

구문

유형 식별자

바이너리 하위 유형

행동

BinData로 변환

숫자 유형에서 binData(으)로 변환합니다.

문자열에서 BinData로 변환

참고

배열로 변환

binData를 배열로 변환

객체로 변환

부울로 변환

정수로 변환

10진수로 변환

double로 변환

비정규 숫자

길게 변환

날짜로 변환

ObjectId로 변환

문자열로 변환

참고

예시

기본 변환 예시

유형 변환 예시

참고

자세히 알아보기

숫자 유형에서 `binData`(으)로 변환합니다.